With OpenAPI, you provide in a declarative, JSON or YAML based format, the technical specification of an API. This documentation contains all necessary data to interact with your API, including endpoints, request parameters (query parameters or body payload) and the responses (status code, data). Furthermore, you can add additional descriptive texts and graphics to further the understanding.
In the last post, I explained in a short tutorial how to write an OpenAPI specification. In this post, I present a selection of documentation generators. Documentation generators take an OpenAPI specification and turn it into a human readable form, mostly HTML pages. The layout of the documentation results vary greatly, as are the features: full text search, fold and unfold code examples, click & copy curl curls, or even execute API calls.
My source is the great list of all OpenAPI tools on openapi.tools. I provide a descriptive overview of those tools that I find helpful.
This article originally appeared at my blog.
Open Source Tools
The community provided several open source tools that are free to use.
RapiDoc
RapiDoc is a customizable documentation viewer. A self-hosted, ready to use version can be accessed here. This tool allows you to load any OpenAPI specification that is accessible via an URL. Paste the link in a small search bar, and shortly after you can view the documentation.
RapiDoc structures the API according to the lexical order of all endpoints contained in the specification. Which HTTP method is used for a specific endpoint is represented in different colors, making the representation rather colorful. When clicking on an endpoint, a new view opens: Request on the left, response on the right side. The request side is particularly complete: Each field shows the complete documentation, including type and description. The request can be viewed as “Value”, showing the data in the preferred data format for that endpoint, and its model, the complete description of the model. The response side also shows an response example and the complete data model.
There is no option to search in RapiDoc.
ReDoc
ReDoc is similar to RapiDoc: A self-hosted documentation viewer with which you can load and view any JSON-Based OpenAPI specification. Beware if you load an extensive specification: The 4MB sized Kubernetes spec loads for about 1 minute!
Redocs’ layout is separated into three different lanes. Left is a list of all endpoints, grouped by the tag value in the OpenAPI specification. In the center you see the documentation of the currently selected endpoint: description, parameters, and responses. And on the right side you see the foldable request data model. There is no option to copy the request body, but you can copy the response data model.
You can also execute a full-text search in the complete API, results are listed in a non-distinguished result box with embedded scroll bars, which makes it hard to find what you are looking for.
Slant
Slant is a document generator that you need to install and host yourself. It is also still in development and cannot be configured to work with an OpenAPI specification — therefore, the screenshots refer to a dummy specification.
Slant uses a three-lane layout. On the left side, you see a dedicated menu: introduction, authentication, the API itself and an errors section. Out of these, only the API section is generated from an OpenAPI specification. It shows the endpoints, and when you click on it, the other two lanes will be updated. In the center, you will see the description and required parameters, on the right side, you will see the returned data structure and examples of how to call the API with basic curl, Ruby, Python or JavaScript.
At the moment of writing, there is no dedicated search function.
Paid Solutions
OpenAPI specifications also get extensive tooling support by different companies. Usually, you get a free account for a limited number of specifications that you want to host.
ReadMe
ReadMe is a tool suite that helps you to create a complete API documentation: The OpenAPI specification is at the core, but can be enriched with additional examples, technical guidelines, and even a support section. Upon registration, you see the different functions and can start right away.
Once you have either manually created the API specification, or uploaded the file, you can see the API documentation in a similar form: endpoint list on the left side, description in the middle followed by code examples how to connect to the API, and then request parameters and responses.
Strangely, you cannot search in the OpenAPI specification itself, but in any of the other artifacts that you provide.
The additional options allow you anything from changing the HTML style, adding integrations to Google or Slack, providing a discussion forum and much more.
Api Matic
API Matic is a tool to build a complete developer portal around your OpenAPI specification. Once you registered, the main admin page shows all “API projects”, and from there you can access each project for editing and configuration.
Once you upload the API specification, you can edit it in a graphical editor, or see the rendered documentation. The API editor allows adding endpoints and data models. You can also define test cases and store access credentials to servers so that other can execute requests live from the generated developer portal. The rendered documentation is separated into three sections. On the left, you can access the getting started part (which is based on additional documentation), the list of API endpoints, and all data models. The middle lane shows the description and properties of the selected element. And if you select an Endpoint, you see a click & copy code example for making an API request.
Searching also occurs in the OpenAPI specification itself, you can quickly find the endpoints that you are looking for.
Additional features are plenty. A handy feature is the conversion from/to the OpenAPI 3.0 specification format, including older versions or schemas such as WSDL, Postman or RAML. And you can also create complete SDKs for languages such as Node, Java, Python, PHP and more These SDKs can be published automatically to Github or a package registry such as NPM.
Swagger Hub
Swagger Hub is a tool for quickly uploading OpenAPI specification and publish the rendered documentation in an open accessible portal. Upon registration, you see a slim interface in which to create and access API specification projects.
Once you uploaded a specification, you can use the editor for modifying the specification, or see the rendered results. Interestingly, I find the editor visually better structured: On the left side, you see the endpoints and the schemas, on the right side the details, and in the middle the JSON format of the speciation.
The rendered documentation instead is vertically aligned, requiring a lot of scrolling. In lexical order of the specification, a list of all endpoints is shown. When you click on an endpoint, you see the description, parameters, and responses with payload data examples. Below the endpoints, you can see all the data models and toggle their description.
You cannot search in the specification. The API view cannot be further configured or changed, at least in my account.
Conclusion
With an OpenAPI specification, you can access a rich toolset that helps you to generate self-contained documentation pages or portals. This article explored 6 documentation generation tools and explained their core features. The common features are to browse endpoints and data models and to see the details of request parameters. Some tools even show code examples for accessing the API, and some even allow a real-time request. The paid tools also give more features to build a complete developer portal: Additional documentation, FAQ pages, and even interactions like a forum.
