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

Tags:

  • Show Comments (15)

  • Raghav

    This is very informative.
    Can someone provide me some information on how to create (soap)api documentation through wsdl (url)

  • John

    Thanks for all of the recommendations. We were looking to implement wordpress with some nice API theme for our SMS platform

  • Jose Galisteo

    Hi, I created https://swaggergo.com

    It is based in swagger-ui. The idea is write your spec (or copy&paste) in a rich editor and later share or embed it in your site with a iframe.

  • Marcin Wosinek

    Right now swagger doesn’t like the https address. The link to go is http://swagger.io/

  • carrie

    What about non-Hosted solutions? My team needs a solution that is hosted in-house.

  • se

    Is swagger documentation free ?
    or do we need to pay license

  • dankan

    cuubez API visualizer is good solution for the java base rest APIs

  • Alex

    Hi Matt,

    I like apiary, but writing documentation in console took some time to learn syntax and I found it not very convenien. A friend of mine suggested me another documentation tool – speca.io. Right now I’m using it in three of my projects and it looks great so far, despite it’s in beta-version. I believe you will find it useful too. Thank you!

  • akshay

    I was certainly finding the one of tool to generate documentation for an web map API, i recently developed. Thanx for the list.

  • Peter

    I create some time ago a small open source tool “apiDoc”
    apidocjs.com
    It creates a documentation from the inline code of an application.
    Example-Documentation: apidocjs.com/example

    It run with nodejs, but it can be used for every programming language, not only JS.

  • Yves Vandewoude

    Hey Matt,

    If you’re documenting Rest APIs, and you’re using Java/JaxRS, you might take a look at MireDot (miredot.com). It grew from a tool we initially developped within our company, to document rest interfaces for our clients. We have recently decided to make this tool publically available (free for open source projects). It’s distributed as a Maven plugin, and uses existing JaxRS annotations and javadoc tags to generate the documentation.

    Regards,
    Yves

  • Andres

    Hi Matt,

    Nice article. We have recently launched Simulty, a website combinator where you can navigate multiple sites simultaneously. I have created an example list taking your selection on this article (giving you, of course, full credit).

    I would ask you for your opinion on how useful can Simulty be for you to promote articles like this one.

    Thanks and regards
    Andrés

  • Ashish

    I have personally used doxygen some 5 years ago on my Java code base. And it was fantastic documentation tool.

  • jonathan

    Originally, on our site, we decided to write free form and then present API Console from Apigee. Definitely room for improvement. Currently evaluating transition to Apiary. Apigee Console is awesome, but free version is not fully integrated with documentation.
    Matt, I recommend you mistake distinction between free and paid tools.

  • Luke Stokes

    Great list, Matt!

    We’re still developing our API, but we’ll be needing to ramp up our documentation efforts as well. I’d love your thoughts on the “interactive link relationship tree diagram”

    We’re doing a Hypermedia API and most of the documentation systems out there I’ve seen focus on the URL which I think is fundamentally flawed as it encourages client developers to code to the URL instead navigating the link relationships.

Your email address will not be published. Required fields are marked *

comment *

  • name *

  • email *

  • website *

Ads

You May Also Like

Tools to generate beautiful web API documentation

In the process of building an API?  Looking to get started on your first ...