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 ?
For Spring based application
Working in a Java shop, I’m looking for a solution at least working for spring-mvc rest services.
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
- RequestMappings – classes and methods annotated with
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.
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
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.
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 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.
sample | sample 2 | springmvc
Customizing it, is also possible.
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 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.)
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 !