Story

I should be able to make API calls to an API endpoint available at api/v1 over https.

This story details how to set this up using the OpenAPI specification

Success criteria

[ ] When I issue a GET request to api/v1/person, I get a JSON response with a person object.

Install the ogen tool using go install -v github.com/ogen-go/ogen/cmd/ogen@latest.
Create a directory api/v1 and cd into it.
Create a file openapi.yaml.
Specify the API call in openapi.yaml.
- Use an openAPI component schema to specify the person object. (refer to OAI service openapi.yaml)
- openapi.yaml of oai service
Copy api/v1/generate.go from the OAI service to the directory api/v1 of the people service.
Run go generate ./... which will generate the server code for the API.
Create a service.go file & implement a Service type:
- The type should satisfy the Handler interface in oas_gen_server.go
- The type should accept the repo as a constructor argument.
- Refer to service.go from the OAI service to see how this is implemented.
Finally initialize and mount the code in cmd/api.go as we do in cmd_server.go in the OAI service.

Initializing the API server:

// setup api
apiServer, err := api.NewServer(api.NewService(repo))
if err != nil {
    return err
}

Hooking the apiServer object in

// mount api
mux.Mount("/api/v1", http.StripPrefix("/api/v1", apiServer))

Documentation:

Refer to the basic guide on swagger.io to see how to create an OpenAPI YAML document.
Look at the swagger editor to see an example.
Look at the openapi.yaml from the OAI service for another example.

n/a/