Unless you’re the only one using the API you just designed, you really need to document it effectively. There are likely many decisions you made when designing and developing the service that might not be obvious to outside developers. Thus, there’s a very high learning curve for someone who uses your API for the first time.

API documentation’s primary goal is to reduce that curve by providing everything in layman’s form. Excellent documentation makes API onboarding much easier — it reduces the time and effort involved in performing integrations for beginner consumers to advanced consumers.

Simultaneously, a self-service API portal can decrease the customer support required of the API provider. Obviously, we need to provide this documentation alongside additional components, community, and support staff. But all of that should be the second option. Consumers should be able to solve their issues by reading the documentation.

Now, there are two ways by which you can generate documentation for your API. The first one is manually writing the documentation. This method requires a lot of time and effort as everything is being done manually, from writing the introductions, versions, to writing a sample output. This is an old fashioned way, but many API developers still follow this method. The second method is using API documentation generators. This method is completely automated and requires very little time — with the right tool, you could generate complete documentation in just 5 minutes. Most of the API-minded companies have switched to this method in some form.

Benefits of API Document Generators

• It saves a lot of time
• It saves resources as well
• You don’t have to update the document again when you make any changes, as these generators can easily pick up the latest changes.
• Versioning is more streamlined

What is the OpenAPI Specification?

OpenAPI Specifications is a common API description format for REST APIs. It is the most broadly accepted standard in the industry. OpenAPI, now on v3, defines a standard, programming language-agnostic interface description for RESTful APIs. It’s community-driven, falling under the OpenAPI Initiative, a Linux Foundation project. With OpenAPI as a backbone, API providers can more easily generate things like documentation, libraries, sandbox environments for testing, and other helpful tools.

So, below, we’ll review some of the best OpenAPI documentation generators. All generators listed here are open-source and most support OpenAPI v3.

1. Redoc

Redoc is one of the best and open-source API document generators that supports OpenAPI v3 specifications. This tool is powerful and highly customizable. Redoc started as an API documentation engine for the Rebilly docs, and later became an independent company. Redoc comes in free as well as paid versions as per your requirements. Redoc is based on React JS and provides a three-column page where in the first column you have your explorer, in the second column you have the description of the selected index, and in the last column, you have a console where you can make API calls.

The first column shows all available endpoints with a little badge to denote the HTTP method, like GET, PUT, POST, etc. The last column also allows you to generate code for calling the API with their payloads. It supports PHP and C#. You can enable and disable CORS too. The tool is also capable of converting markdown into HTML code.

Redoc comes with a CLI tool that lets you check all your Open API definitions from a rule set to ensure you’re following all the OpenAPI best practices. Once you’re ready to publish the docs, you just need to run a single command.

Rebilly API documentation, powered by Redoc

Github Rating: 11k+

Installation Command: npm i redoc

Pros:

• Lots of customization
• Easy to use
• Simple design
• Support for markdown

2. DapperDox

DapperDox is another out-of-the-box open-source solution for authored API documentation. The tool is very flexible and lets you design the documentation pages in the way you want. Like Redoc, it also supports markdown.

DapperDox provides a neat and straightforward user interface with two columns. In the first column, you have your explorer, and in the second column, you have the API method details. It also allows you to customize themes for pages, which are not available in Redoc.

One downside is that DapperDox isn’t updated frequently, and it doesn’t yet support OpenAPI v3. Gauging from this unanswered issue, the maintainers are waiting on an upstream update to a Go parser.

DapperDox demos the Petstore Swagger spec

Github Rating: 284+

Pros:

• Multiple themes option
• Easy to use
• Markdown support

3. WidderShins

WidderShins lets you create API documentation out of OpenAPI 3.0, Swagger 2.0, AsyncAPI 1.x, Semoasa 0.1.0 definitions. Thanks to new features introduced in the latest update, WidderShins now uses promises instead of callbacks, and now it has options to output HTML directly.

The UI of this tool is very similar to ReDoc as it has a three-column page, where in the first column there’s an explorer, in the second column you have the description, and in the third column, you’ll have your console to make API calls as well.

WidderShins uses templates to generate markdown outputs, and you can customize them as per your needs. Mostly it is used in stage environments in the API development pipeline. WidderShins takes an API definition, then converts the written descriptions into markdown or HTML as needed by the renderer like Slate, Shins, ReSpec.

Shutterstock’s API uses Widdershins

Github Stars: 700+

Installation Command:

npm install -g widdershins

Pros:

• Simple and clean UI
• Allows you to generate HTML as well as markdowns

4. SwaggerUI

SwaggerUI, from Smartbear, is another great tool to generate documentation for your API. Using SwaggerUI, one can quickly check which endpoints perform what actions, making it very easy for API consumers to understand the API. SwaggerUI lets you interact with the API without implementing the logic.

It allows you to create API documentation in multiple formats like JSON, YAML, and markdown, making it easier to be edited by anyone. Unlike other tools, SwaggerUI has a single column view where everything is explained neatly in a collapsible bar form. SwaggerUI supports the latest OpenAPI v3 and is well-maintained. It also plays nicely with other Smartbear tools, as we’ve covered previously.

Swagger Petstore documentation

Github Rating: 18.8k

Installation Command:
npm i swagger-ui

Pros:

• Easy to use
• It can deploy API to AWS API Gateway and AWS Lambda
• It can execute API calls from the documentation

5. Lucybot

Lucybot is another API tool that helps developers get started with their own API, and can be used alongside existing API documentation. LucyBot’s DocGen is a static website generator for API documentation.

By creating a cross-language cookbook for all of your API’s major use cases, Lucybot makes it simple to explore API capabilities. The code samples also expand into a visually-rich working demo, so developers have everything they need to get up and running with your API as quickly as possible. It uses OpenAPI, markdown, and other open standards to create highly customizable documentation, as well as an API console and interactive tutorials.

LucyBot provides a unique console to explore API capabilities

Github Rating: 150+

Installation Command:

git clone https://github.com/LucyBot-Inc/documentation-starter

Pros:

• Simple and easy to use.
• Highly Customizable.

6. OpenAPI Viewer

OpenAPI Viewer is an OpenAPI 3.0 and 2.0 Spec viewer with a built-in console. The OpenAPI Viewer works with any framework and also without any framework. The branding and personalization features make it easy to follow any style guide. It has plenty of customizations available, like adding external contents at the top and bottom of the document, adding images, links, forms, and much more.

It also supports searching for end-points, and it has a built-in console to try out APIs. It has a clear separation of Request and Response info laid out side by side in a two-column layout.

OpenAPI Viewer demos the Petstore sample API spec

Github Stars: 150+

Installation Command:

git clone https://github.com/mrin9/OpenAPI-Viewer.git

Pros:

• High customization available.
• User friendly.
• Supports authentication.

7. RapidDoc

Out of all the API documentation in this list, RapidDoc has the best user interface for API documentation. RapidDoc allows you to create beautiful and interactive API documentation using OpenAPI specifications. This tool is very flexible and allows you to customize theme, font, colors. You can also embed external HTML code in the documentation or embed the docs into another HTML code.

RapidDoc comes with a console out of the box, which you can easily use to make API calls and test your API. You can change its attributes using JavaScript as you do in HTML. Like SwaggerUI, it also has a single column view with collapsible bars, and these bars contain the console with the JSON payloads.

RapidAPIDoc offers dark mode, as well as other custom color modes for API documentation

Github Rating: 339+

Installation Command:

git clone https://github.com/mrin9/RapiDoc.git

Pros:

• This tool has the best looking UI
• It supports markdowns as well as HTML
• Comes with lots of themes

8. Elements

Elements is an open-source API documentation project maintained by Stoplight. Using Elements, developers can create embeddable interactive documentation powered by an OpenAPI definition and Markdown. Elements can help generate not only your reference documentation, but tutorials, and how-to guides.

Elements is served as a Web Component or as a React Component. As such, this project would make a lot of sense for frontend web developers already accustomed to React. Stoplight has developed an example site where you can see Elements in action.

Stoplight’s demo showcases its open-source OpenAPI documentation generator.

Github Stars: 1k

Installation Command:

$ npm install @stoplight/elements

Pros:

• React-compatible
• Customizable
• Actively maintained

Benefits of Using Open Source API Documentation Tools

When it comes to API management, there are numerous options available. For example, you could use a fully-fledged API lifecycle management platform that would support documentation generation. These platforms may also provide low-code development capabilities, a developer portal, authentication, authorization, rate limiting, change management, and even monetization features. There is also the opportunity to use more lightweight gateways to wrap your API for more streamlined needs.

But sometimes, large API management solutions are too bulky for the needs at hand. Open-source documentation tools, therefore, are great for scenarios where you simply need to spin up a representation of an API for others to consume. This could be excellent for internal or partner integration situations where you need to document and share the endpoint paths, methods, parameters, and security models. Since many depend on an OpenAPI file, you could easily make this part of your CI/CD build process. Open source is free, easy to use, and white-labeled, so you can mold it to your brand’s style requirements for public-facing situations. Furthermore, most of the projects mentioned above are well-maintained.

Of course, there are potential drawbacks associated with using open-source projects for API documentation. For one, they may not satisfy your entire needs. For example, if you don’t yet have a functional API and comprehensive YAML OpenAPI file, it will not be possible to spin up documentation easily. Furthermore, if you are intending to productize your API, going beyond simply displaying its functionality, you will require additional tools and management capabilities that documentation alone does not provide.

Honorable Mentions

Did we miss any Open Source Open API v3 API Documentation Generator? Please do let us know in the comments.

Final Thoughts

In this article, we have covered the most popular open-source OpenAPI documentation generators. There’s no shortage of documentation generators on the internet, yet these above are the top open-source options that support OpenAPI v3. Maintaining documentation is not an easy task. You have to update the documentation whenever there’s a change made in the API. However these tasks are not being handled automatically by using these documentation generators. Now, API owners don’t have to worry as much about the documentation part and can focus entirely on the API’s development and refinement.