Publishing your API documentation

OpenAPI contains a lot of very valuable information about your API for very different usages. Of course, the main one is documentation, and we will explore it, but there are other usages, such as client code generation or API testing, which we will explore here. But let’s start with documentation.

Using OpenAPI for documentation

There are multiple ways to publish your OpenAPI documentation, but one of the simplest ones is to generate a static HTML page that contains the OpenAPI documentation. Various tools can help you with that, such as Swagger UI, ReDoc, or others. These tools allow you to generate a static HTML page that contains the OpenAPI documentation in a human-friendly format.

Let’s see an example running Redoc with npx, like this:

$ npx @redocly/cli build-docs docs/openapi.yaml

Redoc has generated a static HTML page in the redoc-static.html file. You can open this file in your browser and see the OpenAPI...