BT

Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ

Topics

Choose your language

InfoQ Homepage Research How do you document your APIs?

How do you document your APIs?

Bookmarks

InfoQ's research widget has been deprecated and is no longer available.

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.

 

 

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

  • Sphinx

    by Antonin Kral,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    We are currently using sphinx-doc.org/ even our project is almost solely written in Ruby and Java. We have implemented custom api client / fetcher which fetches API responses and includes them into documentation.

    But it still feels a bit clumsy. And I would say that API documentation is still unsolved problem :)

    Antonin

  • MireDot

    by Peter Rigole,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    We use MireDot in several projects right now and it's awsome! At each maven build, it gives us a fresh documentation on a nice and searchable web page. It also documents the JSON return types with full support of generics. It is Java/JAX-RS based and you can set it up in really no time.

  • Mashape

    by Chris Ismael,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    No option for Mashape? mashape.com

  • Sphinx ?

    by Stefane Fermigier,

    Your message is awaiting moderation. Thank you for participating in the discussion.

  • JavaDoc

    by William Smith,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    We use JavaDoc for us projects and have done for ever. I realise it is language specific but as one of the most established and widely used tools of all I'm surprised it isn't included on the list.

  • Swagger for REST APIs

    by Andrew McVeigh,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    We use Swagger extensively for all our REST and RPC APIs (not for internal Java stuff, but only remote stuff). Works like a complete treat, and Swagger UI is a gamechanger for us - it generates a complete test UI from the Swagger specification for each service.

    RAML looks similarly good.

  • Re: MireDot

    by Harel E.,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    +1

  • 3scale

    by David Valtorta,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Can you add 3scale's API Management Platform to the voting?, im actually using it and i really like it, you should try its free demo.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

BT