IG Group Open-Sources RESTdoclet

IG Group has open-sourced its RESTdoclet Maven plugin for generating web documentation from Spring REST based services.

Why?

REST (fortunately or unfortunately, depending on your ideology) doesn’t benefit from the formal WSDL contract definitions available to SOAP services. It is, by design, nervous of formal interface specifications. Service operations simply conform to ubiquitous web semantics that don’t need specification: operations like GET and POST, which everybody understands.

However, while REST operations may be well-understood, the data types involved are not. Accurate documentation of these types is critical to the successful adoption of the services by consumers.

This is not a new problem, and though there are tools like Swagger and I/O Docs available to generate API documentation from source, in general such tools require either the use of a particular REST framework, or require additional manual configuration. Nor did there appear to be (at time of writing) any tools available to do this easily for the popular Spring REST framework.

IG Group’s RESTdoclet was developed to fill this gap [1], specifically so that it:

• supported Spring 3 REST annotations and JavaDoc out of the box,
• would not require any additional annotations,
• could be easily integrated with a Maven continuous build process, with minimal configuration,
• supported multiple streams of service development, and
• publicised documentation in an interactive, Javadoc-like form, to the web, thus providing a source-code agnostic guide to service consumers.

How does it work?

Let’s say you have built a RESTful Java service, using Spring REST, something like:

/**
* Find sample by unique lookup reference
* 
* @param reference the sample reference, a 5 digit text field
* @return the sample object corresponding to the lookup reference
*/
@RequestMapping(value = "/samples/{reference}", method = {RequestMethod.GET})
@ResponseBody
public Sample getSampleByReference(@PathVariable String reference) {
return service.getSampleByReference(reference);
}
 

RESTdoclet requires that your source code be in a Maven web project, and, since it is a Maven plugin, will require some additional configuration in your Maven pom. This configuration is boiler plate in most cases and can be copied as-is from the RESTdoclet Usage page.

Once configured, the command mvn install –Prestdoclet will generate and install the service metadata into a folder of your choice, as defined by the mandatory environment variable RESTDOCLET_DEPLOY.

In order to view the generated documentation, you will need to deploy the RESTdoclet web application to a web server such as Apache Tomcat. The web app will use the same RESTDOCLET_DEPLOY environment variable to locate the metadata of one or more generated services and display them in a web browser as in the screenshots below.

(Click on the image to enlarge it)

Figure 1 – RESTdoclet service summary page

(Click on the image to enlarge it)

Figure 2 – RESTdoclet service detail page

Where can you get it?

RESTdoclet is available for download as Open Source on GitHub, or in binary form from Sonatype, both under the terms of the Apache 2 license.

Be sure to check out the project wiki for usage instructions, and do feel free to email IG Group at (open.source@iggroup.com) if you have any questions or feedback.

About IG Group PLC

IG Group is a world-leading provider of financial spread betting and CFDs. We are an established member of the FTSE 250 and have a market capitalisation of £1.7 billion (as at June 2011).

With headquarters in London and offices across Europe, as well as in the US, Japan, Singapore and Australia, our international network is growing rapidly. In the last five years we have opened 11 new offices.

The Group has built a reputation for its advanced trading technology, competitive pricing and reliability. We have won a number of awards and independent research has revealed that over 60% of the UK's active spread bettors hold an account with IG Index. [2]

[1] RESTdoclet was built before Spring 3 REST annotations were available, being originally designed to support a proprietary IG Group REST framework, but then later refactored completely when Spring 3 REST became mainstream.

[2] Investment Trends UK Financial Spread Betting & Contracts for Difference Report (November 2011)