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

Introduction

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.

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.

developer's journey

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

developer's journey

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.

developer's journey

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.

developer's journey

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.

developer's journey

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.

developer's journey

Example of an API documentation displayed with Snowboard

Aglio

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

developer's journey

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:

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

Comparison table


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
apiDoc Inline documentation for RESTful web APIs NodeJS apiDoc demo
CuuBEZ API Visualizer Visualize the documentation of RESTful web APIs Java CuuBEZ API Visualizer demo
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

About the author

Diána Lakatos

Senior Technical Writer

Diana is responsible for writing, editing and reviewing software documentation, website copy, user documents, and publications.
Besides working for Pronovix, she's writing reviews for Japanese and Korean TV channels NHK World TV and Arirang TV.

She graduated as a programmer, then went on earning system administrator and system analyst and designer degrees. She's fluent in English and German, and worked as a translator for a publishing company translating books from German to Hungarian. She's the Hungarian translator of Basecamp.

Before becoming a writer, she worked with international clients like Sony Pictures Television, Da Vinci Learning and The Walt Disney Company as a key account manager in integrated marketing campaigns focusing on digital media.