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
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.
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.
Beautiful API references made easy.
Swagger | Markdown
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.
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.
6: API-docs.io — Spotlight
Supercharge Your API Strategy
OpenAPI Specification (Swagger) | RAML
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.
OpenAPI/Swagger-generated API Reference Documentation
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.
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.
An API Blueprint renderer with theme support that outputs static HTML
API Blueprint | Markdown
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.
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.
Miredot generates REST API documentation straight from your existing Java sources!
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 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.
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.
Rapidly Prototype APIs
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
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.
16: SmartDocs — Apigee
Using SmartDocs to document APIs
WADL | Swagger
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
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
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.
19: ASP.NET ApiExplorer — Microsoft
Creating Help Pages for ASP.NET Web API
C# | .NET | XML
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, Download ASP and Web Tools 2012.2 Update here, or read this post on Creating API help pages with ASP.NET for more introduction.
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.
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.
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.
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.
API blueprint parser and renderer
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.
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.
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.
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.”
Inline Documentation for RESTful web APIs
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.
Simply write beautiful API documentation.
Open Source | Markdown | NodeJS
30: Document! X — Innovasys
REST Web Service Documentation Made Easy
WSDL | Swagger | REST | SOAP | Java
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 here. Mashape also designed APIembed for embedding code snippets.
Last but certainly not least, 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.
Have any others in mind? Please comment below!