Generating API docs with the OpenAPI 3.0 spec, Redoc, and auto-generated snippets
In this blog post, we will go through one way of documenting your REST API using the OpenAPI 3.0 standard, Redoc, and auto-generated code snippets. In this post you will find the following sections:
- The OpenAPI 3.0 Specification
- Redoc Integration
- Conclusion & Final Thoughts
An API is a computing interface that defines the requests that can be made to retrieve, change or update information in a web server through endpoints. Most of the popular websites/companies offer an API to interact with their services. Some examples that you can look for are Stripe, Google, Facebook, Twitter, Reddit, etc. The Stripe API, for example, has a very clear documentation, and as such, it can be used as a guideline when organizing your API docs.
To document your API, the most popular methods are based on the OpenAPI 3.0 specification, which was originally part of Swagger. When researching for methods to document, I also stumbled upon Postman’s documentation generator. Postman is a very popular software for API testing, used to make requests and check if the return is what you expected as well as some more complex features. It also has the option to generate documentation that has a similar style to Redoc but does not give you the option to export a static HTML, even if you have a premium account. Besides this, it does not allow exporting the docs to another format. For these reasons, in this tutorial we will be using the OpenAPI 3.0 spec in conjunction with Redoc.
The OpenAPI 3.0 Specification
To use the OpenAPI 3.0 spec you have to write a YAML or JSON file according to the standards defined on the official page. After writing a file with around 10k lines, the biggest drawback I noticed in the OpenAPI 3.0 spec is that sometimes it is necessary to repeat a lot of “code” just to change one word in the response example or to specify different values. This leads to a lot of copy-paste and long files.
In this section, we will show an example of a simple YAML file and a global idea of how it is organized.
Root level object fields
Below are the paths that are on the first level of indentation. The ones marked with an asterisk are required to exist.
We will talk a little bit about the two main sections: paths and components. Paths is where you define all the paths to your API. For each path, you can use the different existent types of HTTP requests such as GET, POST, PUT, DELETE, or others. Then, for each request, you define several fields such as a description, the parameters, and the responses. In the gist below there is a small example of a GET request in the path /people. For a complete list of all the available fields please visit the official swagger openapi 3.0.0 spec website.
To define responses and schemas, we can use the components section. In the example below, we described the Person and Error schemas and then used them to define two responses. In either of them, you might want to define specific examples to give the documentation user an example of possible values the variables can take.
In this GitHub repository you can check the full YAML file.
Redoc is an interactive documentation generator that makes use of the open-source OpenAPI 3.0 specification. In this section, we will go through one possible way of using it during development with VSCode, followed by how to deploy your documentation. Although Redoc has a lot of cool features in their paid version, in this post we are only using the free features.
VSCode + Extensions
VSCode is my editor of choice since it has a large number of very useful extensions that make it usable in most of the existing programming languages. We will use it to edit our YAML file.
To develop and test the API, we will use VSCode and the following extensions:
- ritwickdey.liveserver — Used to host a dynamic HTML file which will be updated upon save, allowing us to see and correct things as we go!
- 42crunch.vscode-openapi — Used for debugging of the OpenAPI specification. It also helps with navigating through sections since it adds a menu on the left side of visual studio.
To render the current YAML file, Redoc provides an HTML file that generates a dynamic webpage that is updated whenever the YAML is saved. You can find it in the Redoc GitHub, in the deployment section. You just need to copy and paste it into an HTML file and change the “Redoc spec-url” to the path to your YAML file.
Now we just need to serve it, if you already installed the liveserver extensions, when right-clicking the HTML file you should see an option saying “Open with Live Server”. This will open a webpage in your default browser.
After developing your documentation, you may want to export it to a static HTML file, instead of having to serve it dynamically. To do this, you can install the redoc-cli locally and then run the bundle command (In Debian-based systems):
sudo apt install node (or preferably directly from the website)
npm install redoc-cli
npx redoc-cli bundle your_file.yaml
Through the Redoc website, you can also import the YAML file and it will generate a website and host it for you for free. Here is my example.
Integrating auto-generated code snippets
Using the node package snippet-enricher-cli, it is possible to integrate some simple code snippets in several languages to your final HTML. To do this, we will need to first generate an output file from the original YAML with the snippets, and then run the new file through Redoc to get the final version. To facilitate this process, we used a simple python script that you can check in this github repository.
Conclusion & Final Thoughts
In this blog post, we learned a little about how to document an API and a method of rendering it in HTML. There are several ways of making documentation, being OpenAPI 3.0 one of the most common ways of describing it. From the specification file, it is then possible to render an HTML file with several tools, from which Redoc was used.
Hopefully this tutorial was helpful. If there is anything you would like to ask please feel free to leave a comment and I will try to get back to you as soon as possible.
Finally, I will leave the link to the GitHub repository with the used files.
Until next time!