BT

How do you document your APIs?

by Jeevak Kasarkod on Nov 05, 2013 |

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.

Tell us what you think

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

Email me replies to any of my messages in this thread

Sphinx by Antonin Kral

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

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

No option for Mashape? mashape.com

Sphinx ? by Stefane Fermigier

JavaDoc by William H

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

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.

+1

3scale by David Valtorta

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

Email me replies to any of my messages in this thread

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

Email me replies to any of my messages in this thread

8 Discuss
General Feedback
Bugs
Advertising
Editorial
InfoQ.com and all content copyright © 2006-2014 C4Media Inc. InfoQ.com hosted at Contegix, the best ISP we've ever worked with.
Privacy policy
BT