In my previous blog entry I described how the REST APIs of Bluemix.info have been implemented. Rather than documenting these APIs somewhere else, I’ve used Java annotations to do this directly in the source code. I think doing this directly in the source code is a good thing since it reminds developers that they have to update the documentation whenever they change the API (or even better don’t change the API in the first place). Plus it’s more efficient to do this in one place rather than having to use another tool.
There are several tools that allow doing this. For Bluemix.info I’ve used the open source project Swagger. Swagger contains several components, most importantly a specification for documenting RESTful APIs. I’ve used the older version 1.2 (but should have used version 2.0 which as I learned today is available now).
In addition to the specification there are many different client libraries and tools for different languages and platforms. For Bluemix.info I’ve used swagger-servlet and declared it in pom.xml as dependency. In order to configure it you need to define ApiDeclarationServlet and DefaultServletReaderConfig in web.xml and tell Swagger in which packages it should try to find the annotations.
To document your REST APIs you need to add additional Java annotations to your classes that are already marked as REST APIs via JAX-RS annotations. As an example check out the API to add authors. Via @ApiOperation the type of operation is defined, as well as the name and protocols. Via @ApiImplicitParams you can define input parameters, e.g. whether they are mandatory or optional, what type they have, default values, etc. And via @ApiResponses you define the possible responses, e.g. HTTP status codes. As input and output parameters you can also use Java classes which is really convenient since Swagger reads automatically the classes’ fields/methods.
Once you’ve added the annotations you can access the definition of your API via URL, e.g. https://www.bluemix.info/api-docs/api.
The other great thing about Swagger is that it comes with a sample UI. This user interface displays the different APIs with their input and output parameters. Plus it allows invoking the APIs directly via some sort of API explorer. You can try it for the Bluemix.info APIs yourselves (but only api/curatednews and api/news can be invoked without authentication).
