Add OpenAPI/Swagger Documentation

[KiwiKilian]

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

[missinglink]

Hi @KiwiKilian, I'm not familiar with either OpenAPI/Swagger.

The Pelias API has been very stable for a long time, so something like this should be easy enough to accomplish.

Can you please explain a little about how these specs are added to a project, in particular if they need to be defined within the codebase or could be externalised?

Regarding Typescript, I recently contributed some types to this repo, how does OpenAPI/Swagger compare to this approach?

[KiwiKilian]

Regarding Typescript, I recently contributed some types to this repo, how does OpenAPI/Swagger compare to this approach?

OpenAPI itself only defines the schema which describes how a spec shall be written. It can be written as JSON or YAML. Swagger is a frontend to view (and edit) such spec more comfortable.

Our use case of generating fetch clients within TypeScript is just one of many. There is a large amount of projects and tools which can generate types/schemas/clients in different languages. Only within TypeScript I know two handful of tools, which use an OpenAPI spec as input and generate typesafe fetch functions. So not only the types of request and response, but also a fetch call with these types connected, can be generated. See for example the list of supported languages only by this specific generator. Using OpenAPI gives the opportunity to generate clients in many different flavors, much superior to providing your own clients in most cases, also requiring much more maintenance. We mainly use @hey-api/openapi-ts which is TypeScript specific.

Looking at you linked contribution this would be part of the output which some of these mentioned tools would generate.

So to conclude, with one well maintained OpenAPI spec many users can generate clients in their specific language/framework. Basically reducing the need of providing a SDK in many languages for your API.

Can you please explain a little about how these specs are added to a project, in particular if they need to be defined within the codebase or could be externalised?

There are many approaches available on different platforms and frameworks to generate an OpenAPI spec for your API, these are just some broad examples:

• Generating the spec directly from controllers/types/serializers (NestJS does this for example)
• Generating specs based on tests
• Manually writing the spec

Looking at the the available libraries for express, there is no clear winner from my point of view. Especially when looking into maintenance/issues/adoption. I also saw, that you weren't to happy about the convoluted approach in the previous PR #1168, which I totally understand. The approach used in that PR is basically still writing the spec by-hand, but co-locates the spec as closely as possible with the implementation in comments above the routes. Based on the size of this API that's probably not much of a benefit.

So without throwing the whole project overboard, most simply the spec can be fully hand written as a JSON file (which I personally prefer over YAML). The biggest concern is to keep the different kinds of documentation in sync with the implementation. Therefore I would prefer to place the file within this repository, also allowing a more versioned approach in-sync with the implementation. Basically if a PR changes the API, it should also update the OpenAPI spec. It would also allow to add a /api/docs endpoint, which shows the Swagger frontend to interact with the deployment, preferably making this configurable.

So if you are generally not opposed, I can try to create a PR with a handwritten OpenAPI spec and the /api/docs endpoint. If you dislike this approach the file can be move to the documentation repository easily.