Rest Api Documentation

The holy grail for rest api is an auto-generated, always up-to-date, stylish documentation that promotes your site/product api. What are the tools available now ?

Inspiring documentation

Well documented

less documented… but strangely easy to use.

For Spring based application

Working in a Java shop, I’m looking for a solution at least working for spring-mvc rest services.

SpringDoclet

SpringDoclet is a Javadoc doclet that generates documentation on Spring Framwork artifacts in a project. The detection of Spring artifacts is based on the presence of Spring annotations on Java classes and methods.

SpringDoclet currently detects and documents the following types of Spring artifacts:
- Components – classes annotated with @Component, @Controller, @Repository, and @Service
- RequestMappings – classes and methods annotated with @RequestMapping

SpringDoclet writes its output in HTML format into a file named spring-summary.html. The location of the file is determined by the Javadoc “-d” option, with the same defaulting rules as the standard doclet.
sample

RESTdoclet

RESTdoclet

Benefits
Enables the creation of an enterprise REST service documentation web portal, providing a central port of call for service consumers
Enables automatic generation of documentation from underlying service source code, thus ensuring the documentation is always up to date
Features
Displays Spring-annotated service operations, types and associated Javadoc
Out of the box supports for Spring 3 RESTful services using Javadoc
Java 5/6 support. Java 7 coming soon
Customisable interactive web documentation application
Simple integration with Maven build processes
No custom annotations required – supports Spring 3 REST annotations out of the box
Further details on the RESTdoclet wiki.

wsdoc

WsDoc is a documentation generator for Spring MVC REST services. Multi modules/war and unified report.

sample

Wadl

Wadl is the wsdl of rest api… but don’t appear to gain in adoption. It’s may dedicated to wsdl nostalgic ;)
Here are some home made solution for self documenting spring based applications.
Sample1 | Sample2

More generics and polished

Swagger

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. The overarching goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters and models are tightly integrated into the server code, allowing APIs to always stay in sync. With Swagger, deploying managing, and using powerful APIs has never been easier.

As a specification, Swagger is language-agnostic. But since a spec without a usable implementation has limited immediate value, Wordnik has released Swagger implementations in Scala, Java, and HTML5. Client generators are currently available for Scala, Java, Javascript, Ruby, PHP, and Actionscript 3. More client support is underway.
sample | sample 2 | springmvc

I/O Docs

I/O Docs is a tool created by Mashery that is very similar to Swagger. Written in JavaScript, the source is available on github (same for swagger), which means that you can taylor it to your own needs, as well as look-and-feel.

sample

Customizing it, is also possible.

apiary

Apiary : REST API documentation. Reimagined.
It takes more than a simple HTML page to thrill your API users. The right tools take weeks of development. Weeks that apiary.io saves.

enunciate

Enunciate is an engine for dramatically enhancing your Java Web service API. (@javax.ws.rs.Path)

It’s simple. You develop your Web service API using standard Java technologies and attach Enunciate to your build process. Suddenly, your Web service API is boasting some pretty impressive features:
- Full HTML documentation of your services, scraped from your JavaDocs.
- Client-side libraries (e.g. Java, .NET, iPhone, Ruby, Flex, AJAX, GWT, etc.) for developers who want to interface with your API.
- Interface Definition Documents (e.g. WSDL, XML-Schema, etc.)
- …

sample

Conclusion

Solutions exists… picking the right one will be harder.
For internal use the doclet approach is perhaps enough. From my point of view swagger looks more promising (specification, multi platform implementation, easy “try it” for end-users,…). I think IODocs will bring too much ‘new’ dependencies for “the Enterprise” (node.js,redis,…).

To go further on this topic, take a look at this presentation maintainable-api-docs-and-other-rainbow-colored-unicorns or this talk

Other remarkable tools ? Don’t be afraid to submit them in the comment !

, ,

  1. #1 by Martin Van Aken (@martinvanaken) on August 15, 2012 - 8:13 am

    api_taster : Rails-specific, and not yet tested, but looks really nice and does not require much work/input : https://github.com/fredwu/api_taster#readme

    • #2 by mestachs on August 15, 2012 - 10:11 am

      indeed quite sexy… I think you should test it ;)

  2. #6 by mestachs on August 27, 2012 - 4:44 pm

    Olivier Bazoud ‏@obazoud

    @ptit_fred Swagger ou Enunciate (utilisé par AXA https://developer.axabanque.fr/api/index.html ) semble pas mal #api #rest #documentation

  3. #7 by fehguy on August 28, 2012 - 11:16 pm

    • #8 by mestachs on August 29, 2012 - 9:57 am

      I don’t see your comment on license. It’s only a roundup,
      I didn’t mention the license… and the “description” is coming directly from swagger site.
      And yes Swagger looks more promising : OSS, multi platform/language, sexy

      • #9 by fehguy on August 30, 2012 - 6:01 pm

        I was referring to this comment:

        I/O Docs is a tool created by Mashery that is very similar to Swagger. The big difference is that it is open source.

        I just want to make sure people understand that swagger is FOSS! Thanks

      • #10 by mestachs on August 31, 2012 - 7:46 am

        updated !

  4. #11 by mestachs on August 31, 2012 - 5:03 pm

    Dave Mosher:
    If you are in PHP land, Frapi (http://getfrapi.com/) can generate the API itself and the documentation.

  5. #12 by Thomas Davis on September 20, 2012 - 12:12 am

    We are working on a service much like Apiary called Api Engine(http://apiengine.io).

  6. #13 by Ittai on November 20, 2012 - 7:40 am

    Thanks! I’ve searched for this exact collection of tools 6 months ago and only found the general ones (swagger,iodocs, etc) but the RestDoclet looks very interesting.
    You sure made my day :)

  7. #14 by hoegertn on December 7, 2012 - 11:58 am

    Hi,
    you might be interested in RestDoc a specification to provide computer readable documentations of REST APIs

    http://www.restdoc.org

    Regards,
    Thorsten

  8. #15 by mestachs on December 13, 2012 - 7:53 am

    search engine for rest api : http://www.apihub.com/

  9. #16 by mestachs on February 5, 2013 - 7:01 am

  10. #17 by Steven Willmott (@njyx) on February 18, 2013 - 5:31 am

    At 3scale we’ve embedded Swagger into our tools and it’s definitely a great framework – specifically we make it hosted so all the front en elements are already hosted for you. I think there’s still a lot to do in terms of formats though so all of the open ones like Swagger, WADL, etc. will hopefully evolve.

    Great summary!

  11. #18 by Mattias Severson on April 2, 2013 - 7:08 am

    Regrettably, Enunciate does not currently support Spring web annotations, e.g. @Controller, @RequestMapping, and friends.

    http://jira.codehaus.org/browse/ENUNCIATE-724

  12. #19 by Yves Vandewoude on May 18, 2013 - 9:24 am

    You should definitely check out MireDot. It grew from a tool we originally developed to document interfaces from projects developed for our clients. It’s a maven plugin that automically generates the rest documentation of your interfaces.

    http://www.miredot.com

    It’s free to use for open source (just mail for a key). The current focus is on json (jaxrs), but the tool is being actively developed. Suggestions or feedback are definitely appreciated and we choose the features to implement based on popular requests.

  13. #20 by chris@mashape.com on June 14, 2013 - 3:25 pm

    How about Mashape? http://www.mashape.com/

    More than a documentation tool, it provides an API ‘forum’ (Issues), analytics, billing platform, and a host of other things. You can check out http://www.mashape.com/howitworks

  14. #21 by snowb0y on June 27, 2013 - 4:57 pm

    On the fate of WADLs I made some attempt to defend them as a a design tool http://blog.fnarg.net/2013/06/24/are-wadls-yesterdays-news/. Of the systems mentioned here I have looked at RestDoc. My experiments with a wadl.json was a bit painful, so I will look into some of the above. Thanks for the write-up.

  15. #22 by mestachs on October 10, 2013 - 4:45 pm

    Stuff are moving… http://raml.org/index.html

  16. #23 by Pavel Shabalin on March 25, 2014 - 6:26 pm

    If you want to get rich documenting functionality along with API design tools and be able to produce beautiful single page documentation you might be interested in the https://speca.io – collaborative platform for REST API specifications. If you have api specification in swagger or wadl format you may try to import and play them out. RAML and API Blueprint support are coming. You also will be able to export you spec to Postman set environment variables and start playing with you API.
    Currently Speca.io is still in active development and totally free.

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

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: