Free and Open Source API Documentation Tools

We explored free and open-source API documentation solutions, and compiled the results of our research in this post.

Definitions

An Application Programming Interface (API) is a set of clearly defined methods of communication between various software components. Organizations share their APIs so that developers can build applications that use the services of their software.

API documentation describes what services an API offers and how to use those services. Good quality documentation is essential to developer experience, which in turn will impact the adoption and long-term success of an API.

We wrote this post for

• API providers: To provide an overview of free and open source tools for companies that want to share, update or customize their API docs or developer portal.
• Developer portal builders: To provide an independent review of existing developer portal solutions that developer teams tasked with building developer portals can use as a reference in discussions with their clients, to make it easier to select the one that best fits their needs.
• Technical writers: To create a resource that tech writers can use to select the API documentation infrastructure that fits best with their existing authoring workflows.

How to choose the right tool?

Identify what your goal(s) are

• To provide a specific experience to users (code samples, language selection options, copy functionality, interactivity)
• To showcase APIs alongside documentation
• To make life easy for documentation authors
• To provide users with try-out possibilities / functionalities to play around with your APIs

What pain points will you come up against?

• Technical learning curve to achieve desired outcome
• Coming up against a paywall for useful features or flexibility
• Unable to grow outside the constraints of the tool as your API program expands
• Security policies
• Responsiveness
• What content to include and how to structure it

How do the tools you use affect your ability to deliver on your goals?

Using open-source tools can be challenging for those who are looking for preconfigured out-of-the box solutions that can address their problems in an instant, as most open-source solutions have different levels of dependencies, e.g., you have to:

• download/use/implement other tools or frameworks,
• configure it first,
• learn the syntax of a new programming language,
• use the CLI (won’t get a visually pleasant interface).

The price of these tools is that you have to find out for yourself how they work through trial and error before you can get the best out of them. Also, as the open-source tools are being maintained by the sacrificial work of the given community, some of them might not get frequent updates. But if you have time and resources, you can configure/edit/update/use them for the tasks you want.

Experimenting with open-source tools is useful and fun, though, because you can build your own toolchain that can do a very specific job for you, but, of course, you have to polish that toolchain constantly.

If you have financial affordance, but you lack other resources, you can purchase a devportal, for example, that does everything you need without the burden of compromise. At least, you don’t have to worry about implementing the solutions you want, because you have a dedicated team. You also pay for the support services, so you can be sure that you get every security and not-so-severe updates and fixes, too.

Open-source API documentation generators

API providers describe their API’s functionalities with specifications and definitions, like OpenAPI/Swagger, RAML, API Blueprint, I/O Docs or WSDL. API documentation solutions convert these definitions into a structured, easy to use API documentation for developers.

API documentation tools are sometimes named after the type of definition they take, e.g., Swagger generates API documentation from Swagger definitions. They also often include the definition in their naming, e.g., RAML 2 HTML.

API documentation generators using the Swagger/OpenAPI specification

The Swagger specification is a powerful definition format that describes RESTful APIs. It maps all the resources and operations associated with a RESTful interface and makes it easier to develop and consume an API.

In 2015, the Swagger standard changed its name to Open API. You can find out more about the initiative at the Open API Initiative website. As a leading standard, Swagger/OpenAPI has accumulated a large range of API documentation generators that use the specification format.

Swagger

Swagger is a complete framework for describing, producing, consuming, and visualizing RESTful web services.

Use the Swagger ecosystem to create your API documentation in JSON or YAML using the OpenAPI definition, and use the Swagger Editor to dynamically convert it into API documentation in a web page.

Your API documentation will be displayed through the Swagger UI, which generates a well structured and good looking interactive API documentation interface that lets you try out the API calls directly in the browser, so you can send requests and get responses back either from a real or a mock server.

Swagger is free to use, licensed under the Apache 2.0 License. You can find all Swagger-related public tools under the swagger-api GitHub account.

Many open-source projects and commercial vendors provide Swagger integrations, so make sure to check out the list of available solutions before building new tooling - there is a big chance you will find an existing solution that fits the needs of your project.

As today’s leading API ecosystem, Swagger is well documented and supported. Should you decide to document your APIs with Swagger, you can find plenty of resources, tutorials, examples and help online.

For further reading:

• Tom Johnson’s OpenAPI tutorial using Swagger Editor and Swagger UI: Overview
• OpenAPI Specification, complete tutorial on GitHub

DapperDox

With the open-source DapperDox, you can author readable guides and have them form part of a cohesive set of documentation along with the API specifications: you can inject relevant documentation into the rendered specification page.

To create your API documentation with DapperDox, point DapperDox at your OpenAPI/Swagger specifications, add some documentation in ** GitHub flavored Markdown** and let DapperDox do the rest.

ReDoc

ReDoc uses the OpenAPI specification and generates a responsive site with a three-panel design. It pulls markdown headings from the OpenAPI description field into the side menu, and supports deep linking.

ReDoc aims to make deployment extremely easy, provides a wide support for OpenAPI objects, and offers interactive documentation for nested objects. You can include code samples via a third-party extension, but it lacks the functionality to try-out the documented APIs out-of-the-box.

Tools you can use to validate or lint OpenAPI specs

• Speccy: With this tool, you can make sure that your OpenAPI 3.0 specifications are not only valid, they are useful as well. Lint the specs against your defined rules, then generate a human-readable documentation. The goal of Speccy is to become the rubocop or eslint of OpenAPI. You can also run it via Docker.
• Spectral: is an open-source tool with which you can lint e.g, OpenAPI/AsyncAPI/RAML descriptions, Kubernetes config, GitHub Actions based on the rules of your predefined style guide. It also has a Stoplight Studio Integration and can be used as a VS Code plugin.
• openapi-lint VS Code Plugin: This extension can be used to validate and lint OpenAPI 3.0.x documents, and convert between OpenAPI 2.0 and 3.0.0.

API documentation generators using the RAML specification

RAML (RESTful API Modeling Language) helps you manage the whole lifecycle of RESTful APIs from design to sharing.

RAML is built on broadly-used standards such as YAML and JSON, and is language neutral with tools for: Java, Javascript, .Net, PHP, Python, Ruby, etc.

To create your API documentation with RAML, you can choose open-source tools like the API Console or RAML 2 HTML. Documentation can be generated quickly and on-the-fly. With parsers available for many languages, you can create your own custom docs and interactive scripts like e.Pages and Spotify.

RAML 2 HTML

RAML 2 HTML is a simple RAML to HTML documentation generator with theme support, written for Node.js.

RAML 2 HTML ships with a default theme, but you can install more from NPM. For example, to render RAML to Markdown, you can install the raml2html-markdown-theme.

RAML API Console

Using the RAML API Console you can create HTML documentation from a RAML specification. It allows browsing of API documentation and in-browser testing of API methods.

There are two ways you can include the console: directly, or within an iframe.

Other tools you can use for parsing, converting, and validating RAML specs

• API Designer: a web-based editor for RAML with a filesystem that has browser integration.
• API Workbench: a full-featured integrated development environment (IDE) for designing, building, testing, documenting, and sharing REST APIs. It supports both RAML 0.8 and RAML 1.0.
• RAML Cop: a command-line tool for validating RAML files.
• RAML Sublime Plugin: a syntax highlighter plugin for the Sublime text editor.
• RAML to PDF: a tool for generating PDF documentation from RAML.
• SOAP RAML Plugin: a plugin for SoapUI that allows you to import RAML files into SoapUI for testing.
• RAML support for Visual Studio Code: a RAML preview, auto-completion, intellisense, and syntax highlighting implementation for VS Code.

API documentation generators using the API Blueprint specification

API Blueprint is a Markdown-based document format for writing API descriptions and documentation. With API Blueprint you can quickly design and create prototype APIs, or document and test already deployed APIs.

Thanks to its broad adoption there is a wide range of tools built for API Blueprint. From various standalone tools such as mock server, documentation and testing tools to full-featured API life-cycle solutions.

Snowboard

Snowboard is an API Blueprint parser and renderer. It offers a colorful default theme illustrating API request types and responses, and can also be used with custom templates.

Aglio

Aglio renders HTML from API Blueprint files, with support for custom colors, templates and themes.

Other free and open-source API documentation generators

Besides the ones detailed above, there are plenty of different open-source API documentation generators for different languages and API specifications. Here’s a brief summary of the ones we’ve explored:

• OpenAPI Generator: Generate clients, servers, and documentation from OpenAPI 2.0/3.x documents. Supports many different integrations and use cases, and customization via options, and custom templates. You can try it out via NPM, Docker, or Homebrew.
• I/O Docs: I/O docs is an API definition format for the TIBCO Mashery network that comes with a live interactive documentation system for RESTful web APIs. By defining APIs at the resource, method and parameter levels in a JSON schema, I/O Docs will generate a JavaScript client interface.
• Slate: Slate helps you create responsive API documentation with a clean, intuitive design. Although it’s built in Ruby, when you write docs with Slate, you’re just writing Markdown, which makes it simple to edit and understand. By default, your Slate-generated documentation is hosted in a public Github repository, which makes it simple for other developers to make pull requests to your docs if they find typos or other problems. Of course, if you don’t want to use GitHub, you can also host your docs elsewhere.
• Whiteboard: A NodeJS based project started from Slate.
• apiDoc: Inline documentation for RESTful web APIs, that creates a documentation from API annotations in your source code.
• CUUBEZ API Visualizer: Java based API solution to visualize the documentation of RESTful web APIs. This API visualizing framework supports all JAXRS based java REST frameworks and non-JAXRS java based REST frameworks that are currently available in the industry.
• Carte: A simple Jekyll based documentation website for APIs. Designed as a boilerplate to build your own documentation, heavily inspired by Swagger and I/O docs.
• Docbox: A responsive website generated from Markdown documentation content. It’s dynamically updated with React.

And a free one:

API Docs: Although not open source, API Docs provides a hosted public API documentation service for OAS (Swagger) and RAML specifications for free. Features like custom domains, themes, and analytics, are available for a nominal cost through the StopLight integration.

General purpose open-source documentation tools

Although very handy, API documentation generators are not the only way to render and display your API docs. Many general purpose documentation tools can also get the job done. You could consider using them if you already have one in place, or if you have more documentation tasks than documenting your API alone.

A couple of documentation tools you can check out:

• Dexy: Dexy is a multi-purpose project automation tool with lots of features designed to work with documents. It does the repetitive parts for you, and thus makes it easier to create technical documents. Many developers use it to document APIs, because combined with other open-source tools, Dexy is able to run your example code, save the results, fetch data from an API, and post your docs to a blog or a wiki.
• Docco: Docco is a quick-and-dirty documentation generator. It produces an HTML document that displays your comments intermingled with your code.
• Doxygen: Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL, Fortran, VHDL, Tcl, and to some extent D. To document your API, generate an online HTML documentation browser or an offline reference manual, and configure Doxygen to extract the code structure from your source files.

We mentioned these tools to give you an idea of how you can use general documentation tools for API documentation, but there are many more to choose from, if you’d like to follow this approach.

Developer portals

Good API documentation is essential, but not sufficient for a great developer experience. It’s better to think about the whole experience in terms of a developer portal that will fulfill all developer needs. Besides the API documentation, a developer portal can include guides and tutorials, reference pages, FAQ, forums, other support resources, software development kits (SDKs), etc. For an overview of all the different types of documentation a good developer portal needs, check our blog post series on developer portal components or receive it as a white paper in your mailbox by subscribing to our Developer Portal mailing list.

We have built and support our Zero Gravity Developer Portal, which is the foundation to the devportal solutions Pronovix implements, using Drupal, an open-source content management system (CMS).

As API documentation is a key requirement, Zero Gravity Developer Portal includes a custom API documentation generator built upon SwaggerUI that can import and render Swagger/OpenAPI files. The generator splits the documentation for individual endpoints into separate entities so that you can control access granularly and easily extend your documentation (especially important for partner portals and for organizations that have strong security requirements). Do you want to document and publish APIs that are not of the REST variety, such as AsyncAPI, GraphQL, SOAP, gRPC, and more? Read our article about the developer portal that can document them all to find more information about the possibilities that Zero Gravity Developer Portal can provide.

Native Drupal also has a couple of modules that you can use to document your APIs, one of which is the API module originally developed to produce the Drupal developer documentation available at api.drupal.org. It implements a subset of the Doxygen documentation generator specification, with some Drupal-specific additions. If you’d like to publish your API documentation and you plan to extend it into a developer portal, you could give Drupal a try, as it’s free, open-source, and has extensive documentation both for the core CMS and the API module.

Conclusion

As you can see, with some research and hopefully with the help of this post, you have a good chance to find an open-source API documentation tool that fits the needs of your project.

Although this article features quite a few solutions, there are many others available or in development, and new ones are popping up continuously. Please let us know in the comments if you’ve tried a solution that you’d recommend to others!

Comparison table

Original article written by Diana Lakatos 30 March 2017, updated by Adam Balogh, Akos Sulyok, and Anett Pozsar 16 May 2022.

All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.