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 !