info.michael-simons.eu

We’ve been using apiDoc.js in a project for a while. While the resulting documentation looks neat, it has several drawbacks in our Java project.

• It depends on the full blown NPM stack, doesn’t fit well in a Maven build stack. It can be done via the grunt-maven-plugin and a gruntfile.js, but this is very hard to explain to Java only developer
• Although the comment syntax looks like JavaDoc comments, it isn’t. And that’s a problem for Java 8 JavaDoc compiler: It fails on most of the “special” terms, so we ended up having several resources files next to our controllers, which contain the documentation. That actually defeats the purpose of apiDoc.js.
• In the end: We are all lazy developers or at least forgetful, so if an API changes, more often then not, we forget to update the documentation

Enter Spring REST Docs. Franz has been tweeting a lot about it lately and after going 1.0, i definitely wanted to check it out.

The head behind Spring REST Docs is Andy Wilkinson and he has done an outstanding job, helping to document existing APIs or prototypes. The documentation alone should answer nearly every question you might have (it would have answered mine if i just had read it better).

I wish i could write a lengthy blog post how hard it was, to an API documentation to my biking Spring Boot demo project, but i can’t.

I basically followed the instruction to add the corresponding maven plugins in the right order as seen in my pom.xml, added an AsciiDoc template for the documentation and then started using my already existing Spring MVC Tests documentation my api:

The result is already online here: Guide and API of biking.michael-simons.eu, the code above creates this part.

I love the beauty of this concept: Leverage existing tests based on Spring MockMvc to generate a tested API documentation: If you add or remove fields, parameters etc. to or from your API, the test will break. Also, documentation and API are in the right place. The toolchain depends on AsciiDoc, but this can easily run with JRuby, so i need no external tooling for generating my application and provide a Maven (or Gradle) based solution for my developers.

One might say Spring REST Docs cannot be used on a whiteboard project or a project designed using WSDL or other tools, but i disagree: Sketching an API using Spring Boot doesn’t take much time and i can always put classes generated from WSDL into a Boot project, use them as parameters or return values and be good.

So if you’re wondering which tool to use to document your api, you should definitively check out Spring REST Docs.