OpenAPI: Documentation Tool Overview

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

RapiDoc

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

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 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

ReadMe

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

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

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

IT Project Manager & Developer