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.

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!

Advertisements

One comment

  1. Pingback: Build Your Own Udemy | APILama

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s