Say you have developed a web API and now want to show it to the world. Next comes documentation, and guess what — there’s a tool for that. But, in a sea of API documentation generation tools, which one is suitable to your specific environment?

This comprehensive list of API documentation solutions has been curated specifically for web API providers. They take an API source, ideally in the form of an API definition, and convert it into nice, presentable documentation that developer consumers can reference.

Before we review each below, let’s first understand the API Definition Languages (DLs) with the most active communities. These make up the majority of tooling available for API providers:

• Open API Specification: Derrived from Smartbear’s Swagger, Open API is becoming the industry standard for API specification. Based on JSON, The Open API Initiative oversees.
• API Blueprint: A powerful high-level API description language for web APIs. API Blueprint is a Markdown-based document format that lets you write API descriptions and documentation in a simple and straightforward way. Developed by Apiary.
• RAML: RESTful API Modeling Language is a machine readable design specification that is human friendly. Based on YAML, developed by Mulesoft.
• I/O Docs: I/O docs is the definition format for APIs created within the TIBCO Mashery network. It defines APIs at the resource, method and parameter levels in a JSON schema. More in-depth definition here.

Other notable API definition languages include: Google Discovery Format, WSDL, WADL, Rapid-ML, HAR, Postman Collection, APIMATIC Format, Mashape JSON Format, Hydra, and others. APIs defined in these ways are machine readable, but require a little more work to create a human readable interface. That’s where our documentation tooling comes in.

In this post we’ve researched open source software like Swagger UI or Slate, licensed software like Readme.io, and API references generated within API management suites such as 3scale. All could be used to generate HTML and CSS to display API methods, parameters, values, requests, responses, code samples, and more.

Some are hosted developer portals, non-hosted templates, or otherwise vary in their feature sets — for example, you may lean toward generating a complete developer center with Gelato, find a design suite for collaboration like Postman Cloud useful, or eschew the frills with a skeleton template like Carte.

But why rely on another dependency for generating documentation at all? Time and cost savings is a good argument. Another is the fact that these organizations have studied the masters of quality API documentation like Stripe or Twilio, and have modeled their static layouts, interactive behaviors, and API explorers, creating sleek approaches for graphically describing a web API. As APIs must transmit data via standard technologies, for the sake of developer onboarding, consistent reference documentation across the industry is a significant plus.

1: Swagger UI

Visualize and interact with API resources
Swagger | Open source
Live Demo

A commonly used option is Swagger UI. Developed by Smartbear, Swagger UI is automatically generated from a Swagger specification, and allows developers to interact with an API’s resources. Since it is open source on Github, the project can be reforked, downloaded, and hosted in any environment. The project’s HTML, CSS, and JavaScript assets will turn a Swagger specification into a human readable presentation, with a wide page dropdown template that documents each method, parameter, and operations. Developers using SwaggerHub to build and design their API will find an easy documentation solution baked in. Swagger has naturally been forked by many others; for an angularJS implementation of Swagger UI, check out angular-swagger-ui.

2: Slate

Beautiful static documentation for your API
Open Source | Markdown | Ruby

Developed by Robert Lord while interning at Tripit, Slate helps you to write API documentation by hand using Markdown. Slate offers an easy template for inputting your API methods, parameters, descriptions, and custom CSS. Inspired by the clean Stripe documentation, Slate generates a three columned layout; company logo with method filtering on the left, API description in middle, and code snippets on the right.

This intuitive design places everything on a single, navigable page with smooth scrolling. On the backend, everything is annotated in markdown — even code samples are written in markdown blocks. Slate also affords syntax highlighting for over 100 languages. By default, your Slate docs are hosted on Github Pages, so you can have free hosting.

An impressive assortment of organizations use Slate, including NASA, IBM, Sony, Travis-CI, Best Buy, and many others. Fore a walkthrough, check out this Sitepoint tutorial on writing API documentation using Slate.

A Blank *Slate* API Documentation

3: Apiary

Blueprint for API Development
API Blueprint | Swagger

Apiary.io is a design stack that enables teams to design, prototype and document APIs. Apiary is noted as the foremost tool for rendering the API Blueprint description language, but it also supports the Open API Specification. Thousands of teams use Apiary to quickly generate the classic three tiered layout, with left hand navigation, human readable functionality in the center, and responsive code snippets on the right. Each action has its own permalink.

Aside from interactive documentation, the Apiary suite provides a description editor, a mock server, debugger, traffic inspector to monitor API usage, and other features included with their plans. Much comes for free, but you’ll need a standard account for embedding a custom API reference on your own domain.

Apiary API Documentation Example: Tesla Unofficial API

4: Readme.io

Beautiful API references made easy.
Swagger | Markdown
Live Demo

Readme.io is a multi-purpose software documentation generator that powers many API developer hubs. It comes with a Markdown-based editor, versioning support, an API explorer to demonstrate sample calls, and crowdsource features where users can suggest API changes.

Something unique to Readme.io is that they provide a template for a full developer portal. Dedicated developer center home pages are great not only for organizing reference volumes, but API home pages also help SEO and allow room for sharing high level descriptions. Box, Yammer, and Mozilla use Readme.io for crafting simple, effective developer documentation.

5: Gelato

Generate Developer Portals from Swagger Specs
Swagger | API Blueprint | Markdown

Developed by Mashape as a documentation generator, Gelato.io can also be used to create complete developer portals. Gelato.io takes a similar hands on approach; it accepts Swagger or API Blueprint uploads, and you annotate in Markdown with a live preview editor. The end result is a nice design with an interactive API explorer and code samples. They provide the ability to serve docs on a custom domain with SSL, and offer additional management features with paid plans. The Gelato.io automatic API explorer is pretty sweet; automatically generated from your API spec, the console lets developers select a resource and action from a dropdown menu, send mock requests, and view responses in JSON.

Gelato’s API Explorer Dock

6: API-docs.io — Spotlight

Supercharge Your API Strategy
OpenAPI Specification (Swagger) | RAML
Live Demo

Stoplight.io converts an OAS or RAML specification into nicely formatted, human readable documentation and hosts it for free on API-docs.io. For extra API lifecycle management features, Stoplight offers an API designer, API testing features, mock web services, and more within their subscription plans.

Using Stoplight’s Hosted Docs, API providers can generate an API playground that covers basic authentication, and allows customized documentation themes and custom business domains. You can choose from a large or constrained layout for a full screen or columned doc approach. For either, standard information for API calls is documented, and developer visitors can view mocked responses using an interactive menu. They offer various themes, custom CSS, and the ability to insert a unique title, logo, and favicon to include business branding. The end result is a great looking flat design with interactive capabilities.

Notable Stoplight.io users include Sendgrid, Chargify, TiVo, vmware, among others. See more doc examples for NPR, Peach, and Giphy. Stoplight, a TechStars company, eats it’s own dog food; their internal API documentation is powered by their documentation service.

7: ReDoc

OpenAPI/Swagger-generated API Reference Documentation
OpenAPI/Swagger 2.0
Live Demo

Nice browser supprt

ReDoc is a new API documentation solution developed by Rebilly. This generator has a comprehensive OpenAPI features support, and produces a nice three panel menu that is mobile responsive and tailored to perform well on all web browsers.

Markdown headings in the OpenAPI description are used in the API introduction side menu, and code samples can be inserted via a third party extension. Under MIT license, ReDoc could pack the same punch as a hosted docs provider, but without the cost. They also have a “Deploy to Github” option to generate a full-featured Github repository for your API.

In the live demo of the infamous Petstore API, you can see nicely structured method calls, and interactive parameters and responsive values. Response codes are clearly noted, and request examples in JSON, C#, and PHP are displayed on the far right. For another implementation example, see how APIs.guru, the burgeoning Wikipedia of APIs, uses ReDoc to document their public-facing API.

ReDoc offers truly mobile responsive layout

8: LucyBot

Helps API providers create a seamless Developer Experience
OpenAPI (Swagger) 2.0 | RAML | API Blueprint | WADL (using LucyBot API spec converter
Live Demo

LucyBot has a few tricks up her robotic sleeves. With an impressive array of API definition language support, the LucyBot API Portal will create static documentation for methods, parameters, and responses. In addition to static documentation, LucyBot will generate an API console to make mock calls, as well as walkthrough recipes for specific programming languages. Notable Lucybot doc users include the New York Times, and Kaltura.

9: Aglio

An API Blueprint renderer with theme support that outputs static HTML
API Blueprint | Markdown
Live Demo

Aglio is an API Blueprint renderer open sourced under MIT license. What sets Aglio apart is its support for custom colors, templates, and various themes. See the Cyborg Two-Columned or Three-Columned themes for an elegant, dark layout. Currently supporting API Blueprint format 1A, using Aglio you can host the resultant HTML on any server. For more, see JetRuby’s blog post that walks through an Aglio implementation.

Aglio’s dark “Cyborg” theme looks just awesome

10: REST United

REST API made easy

REST United specializes in generating and documenting SDKs and sample code. With it you can easily list standard variables, describe operations, all with a responsive layout for viewing requests, responses, and error codes. REST United can auto-generate SDKs for 9 different programming languages: ActionScript, Android, cURL, C#, Java, Objective-C, PHP, Python, Ruby, and Scala.

It seems the REST United team also offers consulting advice on API design and server side code assistance. Notable REST United users include Uptime API, and Hackernews.

11: Miredot

Miredot generates REST API documentation straight from your existing Java sources!
Java

Miredot is an API reference solution designed to be continuously generated upon each build. With a purported 5 minute setup, Miredot is able to detect APIs from certain Java frameworks to convert Java code into documentation. Notable Miredot users include APIman.io, Sophos, NUODB, and others.

12: Postman Cloud

Postman Collection

Postman is well known for its Chrome app “run” button that is used by many developers to quickly test public-facing APIs in a single click — this can integrate with your API documentation, allowing you to onboard developers with more immersive testing capabilities. When it comes to documenting API collections, Postman Cloud recently updated their platform to allow teams to publish documentation to publicly accessible URLs. The documentation for Postman Echo is an example of what their auto-updating API documentation looks like. Postman Cloud also offers collaborative API design and testing capabilities, like creating and sharing API collections, testing scripts, generating code snippets, and more. Notable Postman users include Box and BestBuy. Check out other Postman Cloud features here, or read a more in-depth review by Theodo. To export and document APIs from a Postman collection, the open source postmanerator is also an option.

13: Apidox

Live Interactive API Documentation and Browsing for RESTful APIs.
XML | PHP

Apidox is an XML powered documentation tool for REST APIs. It’s interactive, enabling developers to test API calls from within the documentation. It looks to be a great solution for quickly creating a mock API for developer testing. Apidox implements its own unique definition format; it follows an XML map structure as documented on Github.

Apidox: reminiscent of Apiary but with it’s own style

14: APIMINT

Rapidly Prototype APIs
API Blueprint

APIMINT is an API lifecycle management tool that’s good at quickly prototyping APIs. Using it, developers working in various platforms can define endpoints quickly, or use mock data to quickly see example behaviors. For their documentation, it looks like APIMINT uses Aglio, and then spices that up with some Custom CSS. Auto generation of docs is a nice feature; you’ll have to download these to host yourself.

15: I/O Docs — TIBCO Mashery

Interactive API documentation system
I/O Docs | JavaScript
Live Demo

TIBCO Mashery is a complete API lifecycle management provider; naturally, they provide public documentation solutions for their clients. API Portals on the Mashery Network provide a means to create developer portals and automate the signup process, and generate interactive documentation.

The Mashery Network also supports open source API Power Tools. Available on Github, I/O Docs is an “interactive documentation system for RESTful web APIs.” I/O Docs is Mashery’s approach for defining base API layers in a JSON schema. I/O Docs will generate a JavaScript interface that allows one to execute calls directly from the API documentation. The Mashery API Explorer is built using I/O Docs. Over the years, notable Mashery users have included Rotten Tomatoes and Klout.

Sample I/O Docs from Klout

16: SmartDocs — Apigee

Using SmartDocs to document APIs
WADL | Swagger
Live Demo

Users of the Apigee API management services can use Apigee SmartDocs for generating fully interactive documentation. To Apigee, interactive means reading a description, sending a live request, and viewing a live response. The Apigee Console enables this; allowing developers to filter by methods, query certain parameters or values, and make calls to the API. With an Edge management platform the Apigee Developer Services portal hosts documentation. Though SmartDocs templates are licensed by Apigee customers, you can see them in this Github repository.

17: ActiveDocs — 3scale

Live API documentation
Swagger
Live Demo

3scale ActiveDocs is an offering within the Red Hat 3Scale’s API management toolkit. With a Swagger specification, 3scale will generate interactive documentation that is served and hosted on a provider’s 3scale Developer Portal. 3scale extends Swagger slightly, adding auto-fill of API keys, grouping operations by colors, and supporting complex data types like hash, array, and custom types.

18: RAML API Console — Mulesoft

A Web Component for an interactive REST console based on RAML files
RAML | NodeJS
Live Demo

Using RAML Console, API providers can showcase a RAML API definition using HTML in a browser, and test methods. It can be implemented directly or by using an iframe. Mulesoft’s Anypoint Platform also offers a developer portal, integration capabilities, and the means to design and collaborate on API designs, deploy, and publish documentation. The documentation creates a two columned display with expandable methods, which allow live testing with user credentials.

Mulesoft Sample RAML reference docs

19: ASP.NET ApiExplorer — Microsoft

Creating Help Pages for ASP.NET Web API
C# | .NET | XML
Walkthrough

The ASP.NET APIExplorer is a class that allows developers working with the ASP.NET Web API framework to create static documentation of their HTTP methods and URIs. ASP.NET Web API is a framework for building APIs on top of the .NET framework; if you work in C# this is the tool for you.

The ASP.NET Web Tools package has built in features for auto generating API documentation. This churns out a left column that lists the API method and relative UI, as well as a center column that describes each function, and there is the ability to create custom styles and layouts.

The NuGet Package Manager can add help pages to an existing web API written in C# or VisualBasic. XML documentation comments are used to describe methods and parameters. Building within Microsoft’s desktop application, the menu allows this to occur on top of the ApiExplorer class; part of the web API framework. ApiExplorer treats each method as its own API. To get started, read this post on Creating API help pages with ASP.NET for more introduction.

20: Speca.io

Web API focused documentation platform
Swagger | WADL

Speca.io, still in Beta, looks to be a competitor in the web API documentation market. Inspired by docs like Twitter or Stripe, Speca offers a navigable, user friendly API documentation and an embedded API console. The Editor allows you to define API headers, parameters, maintain different versions of the API, and export to Postman or Swagger. While Speca.io is still in beta, you can browse the API docs that have been added here.

Marvel Public API v1 Docs using Speca

21: Restlet

Enhanced API documentation
Swagger | RAML

Restlet provides a platform for easily delivering APIs. A recent announcement signalled that Restlet Studio, the API design tool, now provides hosted documentation, including automated doc creation for Swagger and RAML API definitions. For more see the Restlet user guide on creating API documentation.

Example of Restlet API Documentation

22: RepreZen

Design, document & deliver world-class APIs in one, fully-integrated workbench
Swagger-OpenAPI 2.0 | RAPID-ML

Reprezen API Studio provides a complete IDE for collaborative API lifecycle management. Built around the OpenAPI Specification, Reprezen offers live documentation generation as you edit. It could be great for larger projects as it allows you to split a Swagger Specification across multiple files. As RepreZen’s output is Bootstrap-based, customization is endless with Bootstrap skins and custom CSS. Also, RepreZen diagram is a novel approach to graphically depicting API structure and hierarchy that fits the RAPID-ML API modeling language.

23: Carte

Simple Jekyll-based documentation site for APIs.
Jekyll | YAML

Inspired by Swagger and I/O Docs, Carte is an open source foundation for building your own API documentation. Carte offers a simpler way to describe APIs, focusing on JSON objects and producing a basic docs template built with Github’s Jekyll, the static site generator.

Simplistic Carte API Documentation Template

24: Snowboard

API blueprint parser and renderer
API Blueprint

Snowboard is another open source API blueprint renderer. Under MIT license, Snowboard can generate HTML documentation and serve via HTTP. It has a colorful default theme to illustrate API request types and response content.

25: raml2html

RAML to HTML documentation generator.
RAML | NodeJS

raml2html is a project on Github by Kevin Renskers which could act as an alternative to the RAML Console. Dropdown menus illustrate parameter functions, and lightboxes showcase further request details. With a simple two column layout and color highlighting for different HTTP calls, raml2html is a functional, simple documentation solution for self-hosting a RAML reference.

26: Read the Docs

Create, host, and browse documentation.
Live Demo

Read the Docs is a popular multi-purpose software documentation template that could be used to document RESTful APIs. Auto-generation of API documentation using Read the Docs is not possible alone; as a workaround, this developer uses sphinx-apidoc to auto generate documentation, and commit files to a Github repo so that Read the Docs can convert it into HTML.

27: Dexy.it

make | docs | sexy
Python | Agnostic

Dexy.it is similarly a general purpose documentation tool written in Python that some developers use to document their APIs. Dexy configuration files act as filters that scan files to perform functions based on file types. Language agnostic, Dexy provides a standardized method way to refer to areas in your project. In conjunction with other open source software, you write expressions that act as filters to detect portions of your content to be redisplayed in another document.

“Dexy’s filters do things like run your code and make it pretty, but they can also do just about anything else, like post your docs to a blog or a wiki, or fetch data from an API.”

28: apiDoc

Inline Documentation for RESTful web APIs
NodeJS
Live Demo

apiDoc produces API documentation using annotations within your code. ApiDoc acts as a parser, detecting apiDoc parameters within comments like @apiDefine for method descriptions or @apiExample for example usages of an API method. Using these cues, apiDoc generates a clean two-columned API documentation with call type, parameters, error responses, and other standard requirements.

See an APIDOC live sample here

29: Whiteboard

Simply write beautiful API documentation.
Open Source | Markdown | NodeJS

Whiteboard began as a fork of Slate. As Slate is Ruby-based, Whiteboard is written in NodeJS, allowing an apparently easier setup process. The Whiteboard documentation looks identical to Slate, but will appeal more to JavaScript users who are seeking an intuitive “npm install” and “npm start”.

30: Document! X — Innovasys

REST Web Service Documentation Made Easy
WSDL | Swagger | REST | SOAP | Java
Live Demo

Innovasys’s Document! X can take a Swagger or WSDL API descriptions and produce static documentation, as well as a data tree that visually illustrates the data hierarchy. The end result is a basic two-columned documentation that organizes calls into description, parameters, responses, and error responses. Document! X looks good for documenting SOAP/XML web services.

31: Mashape Marketplace

Mashape JSON Format
Cloud API Marketplace where developers can easily consume Cloud APIs

Any API provider can choose to list their API for free on the Mashape Marketplace. Doing so will generate basic API documentation. To do so, you define your authentication mechanisms, and manually add API endpoints using their user interface. Mashape API management features appear to target small API side projects, offering plug and play abilities for creating a developer portal. They offer a nice walkthrough of the documentation process. Mashape also designed APIembed for embedding code snippets.

32: Hitch

Hitch hq is a marketplace for APIs where providers can list their service, take advantage of API management features, and maintain a public-facing developer portal. It can also be used to track changes across hundreds of APIs throughout the industry.

Hitch will automatically generate documentation from a Swagger or RAML file, and they help companies create machine-readable documentation if they don’t already have it. API developer centers on Hitch can include the API reference, SDKs, how-to guides, a changelog, and more. The Hitch documentation features a simple interactive menu to reference calls and discover parameters and responses, as shown below.

Hitch documentation Slack API example

33: DapperDox

Beautiful, integrated, OpenAPI documentation
Swagger / OpenAPI Specification | Open Source
Live Demo

DapperDox is an open source generator for documenting OpenAPI APIs. A unique element of DapperDox is that in addition to creating documentation, it generates guides and diagrams, enabling you to write this in a Github flavored Markdown. Other features include an API explorer, theme customization, and the ability to document multiple services.

DapperDox is an open source doc generator for OpenAPI Spec APIs

34: APITree

Create, manage, and share API documentation
Auto-gen from OpenAPI v2 / v3 Specification
Live Demo

With APITree you can convert your OpenAPI v2 / v3 specification into beautiful technical API documentation. Public APIs are hosted for free on the APITree HUB. Internal APIs can be kept private and shared with clients directly.

Others

• ClickHelp

Have any others in mind? Please comment below!