OpenAPI example

Prerequisites

Language-specific tools - Install Heim Prerequisites
Heim cli and runtime - Install Heim
Text Editor - VsCode is a great option with language-specific plugins
Terminal - Heim is accessed through its command-line interface

Guide

Prepare your OpenAPI specification or use this one below and save it to a file called specification.json:

{
    "openapi": "3.0.3",
    "info": {
        "title": "Demo Geolocation",
        "version": "1.0.0",
        "description": "API for geolocation services including image processing, country retrieval, and sun timing."
    },
    "tags": [
        {
        "name": "geo-location",
        "description": "Operations related to geolocation services."
        }
    ],
    "components": {
        "schemas": {
        "Coordinates": {
            "type": "object",
            "properties": {
            "latitude": {
                "type": "number",
                "format": "double",
                "description": "Latitude of the location."
            },
            "longitude": {
                "type": "number",
                "format": "double",
                "description": "Longitude of the location."
            }
            },
            "required": ["latitude", "longitude"]
        },
        "GeoLocationResponse": {
            "type": "object",
            "properties": {
            "latitude": {
                "type": "number",
                "format": "double"
            },
            "longitude": {
                "type": "number",
                "format": "double"
            }
            }
        },
        "CountryResponse": {
            "type": "object",
            "properties": {
            "country": {
                "type": "string",
                "description": "Name of the country."
            }
            }
        },
        "SunTimesResponse": {
            "type": "object",
            "properties": {
            "sunrise": {
                "type": "string",
                "format": "time",
                "description": "Time of sunrise."
            },
            "sunset": {
                "type": "string",
                "format": "time",
                "description": "Time of sunset."
            }
            }
        },
        "SunTimesRequest": {
            "type": "object",
            "properties": {
            "coordinates": {
                "$ref": "#/components/schemas/Coordinates"
            },
            "date": {
                "type": "string",
                "format": "date",
                "description": "Date for which to retrieve sun times."
            }
            }
        }
        }
    },
    "paths": {
        "/extract-geo-location": {
        "post": {
            "tags": ["geo-location"],
            "summary": "Extract Geo-Location from Image",
            "operationId": "extractGeoLocation",
            "parameters": [
            {
                "name": "Authorization",
                "in": "header",
                "required": true,
                "schema": {
                "type": "string"
                }
            }
            ],
            "requestBody": {
            "required": true,
            "content": {
                "application/json": {
                "schema": {
                    "type": "object",
                    "properties": {
                    "image": {
                        "type": "string",
                        "format": "binary",
                        "description": "Base64 encoded image."
                    }
                    },
                    "required": ["image"]
                }
                }
            }
            },
            "responses": {
            "200": {
                "description": "Geo-Location coordinates extracted successfully.",
                "content": {
                "application/json": {
                    "schema": {
                    "$ref": "#/components/schemas/GeoLocationResponse"
                    }
                }
                }
            }
            }
        }
        },
        "/get-country": {
        "post": {
            "tags": ["geo-location"],
            "summary": "Retrieve Country Name from Coordinates",
            "operationId": "getCountryFromCoordinates",
            "parameters": [
            {
                "name": "Authorization",
                "in": "header",
                "required": true,
                "schema": {
                "type": "string"
                }
            }
            ],
            "requestBody": {
            "required": true,
            "content": {
                "application/json": {
                "schema": {
                    "$ref": "#/components/schemas/Coordinates"
                }
                }
            }
            },
            "responses": {
            "200": {
                "description": "Country name retrieved successfully.",
                "content": {
                "application/json": {
                    "schema": {
                    "$ref": "#/components/schemas/CountryResponse"
                    }
                }
                }
            }
            }
        }
        },
        "/sun-times": {
        "post": {
            "tags": ["geo-location"],
            "summary": "Retrieve Sun Rise and Set Times",
            "operationId": "getSunTimes",
            "parameters": [
            {
                "name": "Authorization",
                "in": "header",
                "required": true,
                "schema": {
                "type": "string"
                }
            }
            ],
            "requestBody": {
            "required": true,
            "content": {
                "application/json": {
                "schema": {
                    "$ref": "#/components/schemas/SunTimesRequest"
                }
                }
            }
            },
            "responses": {
            "200": {
                "description": "Sun rise and set times retrieved successfully.",
                "content": {
                "application/json": {
                    "schema": {
                    "$ref": "#/components/schemas/SunTimesResponse"
                    }
                }
                }
            }
            }
        }
        }
    }
}

Start by running heim new to create a project from a template.

Use the up/down arrow keys to select the template and press enter:

heim@system:~/repos$ heim new
? Select template:  ›
c-http
csharp-http
csharp-http-async
go-http
python-http
rust-http
typescript-http
...
❯  openapi-specification
...

Next, we will choose the language that our OpenAPI specification will generate code for.

For this we will choose C#:

✔ Select template:  · openapi-specification
? Select language:  ›
Rust
...
❯  Csharp
...

Next, we will enter the path to where you saved your specification.

✔ Select template:  · openapi-specification
✔ Select language:  · CSharp
OpenApi-specification (File-path / Uri): specification.json

Next, we will enter the application name.

✔ Select template:  · openapi-specification
✔ Select language:  · CSharp
✔ OpenApi-specification (File-path / Uri): specification.json
'Project name': MyProject

Next, we will enter the application version, in the format of semantic versioning (major.minor.patch).

For this we will use the default value of 1.0.0

✔ Select template:  · openapi-specification
✔ Select language:  · CSharp
✔ OpenApi-specification (File-path / Uri): specification.json
✔ Project name: MyProject
Version: [1.0.0]:

Next, we will enter the base path for the application

The path has to start with /

✔ Select template:  · openapi-specification
✔ Select language:  · CSharp
✔ OpenApi-specification (File-path / Uri): specification.json
✔ Project name: MyProject
✔ Version:: 1.0.0
Base-path:  [/example/path]: /MyProjectPath

Rendered Template: ".gitignore"
Rendered Template: ".heim/GeoLocation.cs"
Rendered Template: ".heim/Json.cs"
Rendered Template: ".heim/Router.cs"
Rendered Template: ".heim/WasiEventLoop.cs"
Rendered Template: "GeoLocation.cs"
Rendered Template: "application.toml"
Rendered Template: "component.toml"
Rendered Template: "my-project.csproj"
Rendered Template: "my-project.sln"
Rendered Template: "nuget.config"
Rendered Template: "wit/types.wit"
Rendered Template: "wit/world.wit"
[00:00:00] ########################################      13/13      Success
INFO [ Heim new ] New component created: Some("/home/heim/repos/MyProject")

Once we’ve gone through all the previous steps, we’ll have a project ready to go.

The full code is available in our Github repository here
Now you have a created application ready for you to implement your solution in. In the GeoLocation.cs file you will find a few comments that read // REPLACE WITH IMPLEMENTATION, this is where you implement your solution.
For more information about C# you can check out our basic C# template:
Basic C# application