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.
Recently 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: document APIs with JSON using the Swagger spec, and use the Web UI to dynamically convert it into API documentation in a web page. Your API documentation will be displayed through the Swagger UI, which provides a well-structured and good-looking interface.
Example of an API documentation displayed with the Swagger UI
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 tools 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, it’s also the best documented and supported. Should you decide to document your APIs with Swagger, you can find plenty of resources, tutorials, examples and help online.
DapperDox
With 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 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.
API documentation generators using the RAML specification
RAML (RESTful API Modeling Language) helps you manage the whole API lifecycle 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.
Example of an API documentation displayed with RAML 2 HTML’s default theme
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.
Example of an API documentation displayed with the RAML API Console
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 prototype APIs to be created, 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 colourful default theme illustrating API request types and responses, and can also be used with custom templates.
Example of an API documentation displayed with Snowboard
Aglio
Aglio renders HTML from API Blueprint files, with support for custom colors, templates and themes.
Example of an API documentation displayed with Aglio (Cyborg two-column theme)
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:
- 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.
- Apidox: XML powered live interactive API documentation and browsing for RESTful APIs.
- 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:
- 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 necessary, but not sufficient for a great developer experience, so 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, FAQs, forums, other support resources, software development kits, 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.
At Pronovix, we work with Drupal, an open source content management system to build a full-featured developer portal, a toolbox for developer relations with integrated API documentation.
Drupal 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.
We have done extensive work with Apigee’s developer portal that is built in Drupal 7, and we are building a new developer portal in Drupal 8, Drupal’s latest release. As API documentation is a key requirement, it will include a custom API documentation generator that can import Swagger/OpenAPI files and that 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 organisations that have strong security requirements). Our ultimate goal is to share our developer portal package as an open source Drupal distribution.
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!
Reference
| Quick summary | Source (specification) | Live demo | |
|---|---|---|---|
| Swagger | Whole ecosystem, lots of integrations Good-looking UI for docs Widely used, many resources available |
Swagger/OpenAPI | Swagger demo |
| DapperDox | Inject relevant documentation right into the rendered specification page | OpenAPI, Markdown | DapperDox demo |
| ReDoc | Easy deployment Wide support for OpenAPI objects Interactive, responsive documentation |
OpenAPI | ReDoc demo |
| RAML 2 HTML | Simple RAML to HTML documentation generator theme support | RAML, NodeJSwith | RAML 2 HTML demo |
| RAML API Console | Browsing of API documentation and in-browser testing of API methods | RAML, NodeJS | RAML API Console demo |
| Snowboard | API Blueprint renderer | API Blueprint | Snowboard demo |
| Aglio | API Blueprint renderer with many custom themes | API Blueprint | Aglio demo |
| I/O Docs | Live interactive API documentation system for I/O Docs specification format | I/O Docs (JSON) | I/O Docs demo |
Slate |
Clean, intuitive design Write in Markdown Collaboration through GitHub |
Markdown (Ruby) |
Slate demo |
| Whiteboard | NodeJS based Slate alternative | NodeJS | Whiteboard demo was from wifidistribution.com/docs, no longer available as of May 2019 |
| apiDoc | Inline documentation for RESTful web APIs | NodeJS | apiDoc demo |
| CuuBEZ API Visualizer | Visualize the documentation of RESTful web APIs | Java | CuuBEZ API Visualizer repo |
| Apidox | XML powered live interactive API documentation and browsing for RESTful APIs | XML, PHP |
Apidox demo |
| Carte | A simple Jekyll based documentation website for APIs |
Jekyll, YAML | Carte demo |
| Docbox | A responsive website generated from Markdown documentation content | Markdown | Docbox demo |
| API Docs |
Free, hosted API documentation | OpenAPI, Swagger, RAML | API Docs demo |
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.