BT
x Your opinion matters! Please fill in the InfoQ Survey about your reading habits!

IG Group Open-Sources RESTdoclet

by Robert Morschel on Aug 13, 2012 |

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)

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread
Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Discuss

Educational Content

General Feedback
Bugs
Advertising
Editorial
InfoQ.com and all content copyright © 2006-2014 C4Media Inc. InfoQ.com hosted at Contegix, the best ISP we've ever worked with.
Privacy policy
BT