Tools to generate beautiful web API documentation

Edit 6/16/2013: It’s been a few months, and we finally ended up going with the Swagger-based documentation built into 3Scale.net.  Want to see how it looks?  Head over to developer.nutritionix.com.

— Begin original post —

As demand for our Nutritionix API is starting to grow rapidly, we have been working on finding an API documentation engine to meet our needs for the long-term.  I was not able to find any comprehensive list of existing API documentation solutions, so I am compiling what I have found so far. Please leave feedback on your own experience in the comments.

Web API Documentation Tools

We are still exploring each solution, but I will update this post as we learn more about each option.

  • Swagger – A specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. [Demo]
    • Note: We already use 3Scale.net for our API management solution, and they have an ActiveDocs feature based on Swagger.
  • I/O Docs – By defining APIs at the resource, method and parameter levels in a JSON schema, I/O Docs will generate a JavaScript client interface [Demo].  I/O docs was created by the API management platform Mashery.
  • apiary.io – Provides very quick way to get your documentation up and running, includes GitHub integration and I/O validation. – Suggested by Siyfion via Reddit.
  • Docco – Docco is a quick-and-dirty, hundred-line-long, literate-programming-style documentation generator. It produces HTML that displays your comments alongside your code.
  • Dexy – Flexible documentation tool that supports any language, for any API.
  • Doxygen – Generate an on-line documentation browser (in HTML) and/or an off-line reference manual, and you can configure doxygen to extract the code structure from undocumented source files.  Seems more technical than the other options, but a powerful option nonetheless.  Suggested by gkumar007 via Reddit.
  • TurnAPI – Paid service.  Intelligent WIKI-editor, markdown based standards, documentation branching, sync with Git, SVN, Mercurial, clean looking themes. [Features]
    • Note: As of writing I was unable to create an account at TurnAPI.

Edit 6/16/2013: It’s been a few months, and we finally ended up going with the Swagger-based documentation built into 3Scale.net.  Want to see how it looks?  Head over to developer.nutritionix.com