Add OpenAPI/Swagger Documentation

Use-cases

We want to generate typesafe clients in TypeScript for interacting with the pelias HTTP API. This is often accomplished by generating from OpenAPI specs. These specs basically document the requests and responses of an API and their endpoints. The spec can then be used to generate clients in many languages and helps in general to debug or test an API.

Attempted Solutions

#1168 already started this process but got stalled.

Proposal

• Add or generate an OpenAPI spec to the api OR Documentation repository
• Add an endpoint which serves the Swagger UI, which makes the OpenAPI spec easily visible (optional)

I'm opening this issue to see if the pelias project would be interested in OpenAPI and if we should invest the time to open another PR. Depending on the implementation, this could also be just an OpenAPI spec living within the documentation repository. Preferred would be defining the spec close to the code and adding the Swagger UI, which would allow to verify deployments easily – that's why I've openend the ticket in this repository.

References

#1168

Start by reviewing the stalled implementation in #1168 and inspecting how the Pelias HTTP API endpoints are defined. Decide whether the OpenAPI spec belongs in the API or documentation repository, and whether a Swagger UI endpoint is in scope. Done means the API is described well enough to generate typesafe clients, with the optional UI available if adopted.