Documenting Spring RESTful APIs

Lately, I’ve been writing alot of RESTful services using the Spring framework and its @RestController. The only thing I really missed was an easy way to document the RESTful API. I’ve looked into various options, and like most people, I found that Swagger seemed to be the only viable option. However, after having tried it, I found some serious issues. Besides being a very bulky dependency to have to include, having a visually attractive but very cluttered front-end in the form of SwaggerUI, what I disliked the most was the pollution of my code with alot of additional annotations.

Then I ran into Andy Wilkinson’s webinar on the topic. Andy clearly demonstrates the problems with tools like Swagger. He concludes his webinar by promoting his own tool on github to document restful services. I checked out his project and found two concepts he uses very interesting. First, he generates documentation from a unit test thus not polluting your production code. Secondly, he promotes the use of handwritten documentation for all cross-cutting concerns, such as the use of HTTP verbs, return codes, and error handling, which of course should all be the same for any of your services. What I personally found less appealing about his tool was the fact that you have to write alot of static documentation yourself and that there really is not much documentation being generated. So in the end, I also end up not using Andy’s tool.

So the only thing left was to write my own tool. And that is exactly what I did. You can find a very rough, first version of SpringRestDoc over on bitbucket:https://bitbucket.org/tritales/springrestdoc/.

The basic ideas behind SpringRestDoc are:

1. Only document classes annotated with Spring’s @RestController;
2. Have the tool generate as much information as possible;
3. Use it from a unit test so your production code doesn’t get polluted;
4. Have the option to generate JSON for use in your custom front-end;
5. Have the option to generate an asciidoc fragment to include in your general documentation, which preferably describes the cross-cutting documentation;
6. Optionally use Javadoc comments to include additional information.

There is still some work to be done, but do go on and check out the project and do let me know what you think of it.

Update March, 3rd 2015

A first version of SpringRestDoc has been published to the Maven central repository. You can include it in your project by adding the following lines to your pom.xml: