How do you document your APIs?
Well documented APIs enhance the experience for developers and have become an essential requirement for defining an API’s success. Good documentation is no longer just about clarity of the prose but also improving the affordance of documents as live API experiences for developers. As a result, there are a variety of tools targeted at API producers to automate the process of generating richer documents that reduces costs and time and dramatically improves developer adoption.
Given the fact that APIs are becoming the face of businesses and that documentation plays such a vital role in its adoption, we want to know which of these tools you are using or intend to use and your opinion on their relative relevance:
- Swagger – A specification and complete framework implementation for describing, producing, consuming, and visualizing
RESTful web services. Swagger is language agnostic.
- Mashery I/O Docs– Mashery I/O Docs uses a JSON schema to describe APIs resources, methods and parameters.
The schema is extensible.
- Apiary.io – API blueprints are specified using a specialized Markdown syntax to get documentation up and running.
- MuleSoft API Designer & Console – API Designer and API Console are RAML based tools.
- Apigee Console To-Go – An interactive console defined using WADL and Apigee specific extensions to the WADL spec.
- ASP.NET API Explorer – IApiExplorer is an abstraction layer that allows you to obtain a description of the structure of your
Web APIs. ApiExplorer is the default implementation of IApiExplorer that inspects the routes and other Web API
constructs to produce the description. This feature is currently available as part of our ASP.NET Web API project
- Docco – Docco produces an HTML document that displays your comments intermingled with code. All prose is passed through Markdown, and code is passed through Highlight.js syntax highlighting.
- Dexy – Dexy is a general purpose documentation tool that supports any language and could also be used for documenting
- Doxygen – Doxygen is also a general purpose documentation tool that can be used for documenting APIs too.
It generates either an on-line documentation browser (in HTML) and/or an off-line reference manual from documented
- TurnAPI – TurnAPI is a text-to-HTML conversion tool for web writers that is based on markdown standards.
- Enunciate: Enunciate is an open-source documentation generation engine that is attached to the Java build process to
generate HTML documentation.
- MireDot: MireDot combines data from various Java frameworks such as JavaDocs, Jax-RS, Jackson etc to
- sphinxcontrib.httpdomain: sphinxcontrib.httpdomain is an extension to the general purpose documentation tool
Sphinx for Python and C/C++. It generates documentation for RESTful APIs and has additional modules for supporting
frameworks such as flask, bottle etc.
Obviously there are more options to document APIs except RAML, API Blueprints and the others mentioned here. I just wanted to provide an overview of some historical approaches as well in this post.
I would love to hear your feedback and listen to your opinion at the poll I have created about API standards and what you guys tend to use.
You can share the poll by communicating the poll page with your fellow APIartisans!