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 on CodePlex.
• 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 Web APIs.
• 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 source files.
• 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 generate documentation.
• 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.