Beautiful API documentation with negligible overhead
This is our story on how we saved a lot of time writing API documentation and archived a better experience for producers and consumers of the API. As most programmers we didn’t like spending time on documenting the API we were working on.
We started out with a single Google Docs document. Initially, this solution allowed us to write documentation without any additional setup, but as it grew we encountered a lot of problems. A 50-page Google Docs document takes some time until it is fully loaded. But it was even more annoying to get the formatting consistent and therefore it was not a surprise that the documentation was quickly outdated. It was obvious that we needed a better solution.
We researched several options. A lot of us have worked with Swagger before, but Swagger makes it hard to produce a readable documentation with examples and explanations not directly corresponding to a single endpoint. Specification based solutions like RAML, API Blueprint, or Apiary come with the overhead of maintaining the API in two places: code and a description language. With Spring REST Docs we discovered another solution that looked promising. This project tries to mitigate the weak spots of the projects mentioned above. However, it only works for Java applications that can be tested with the Spring MVC Test framework. After several discussions we decided to give it a try.
Spring REST Docs combines hand-written documentation with snippets generated out of tests. Asciidoctor is used to turn everything into a HTML page. Writing AsciiDoc is a relief after trying to get the formatting right in Google Docs. For the tests you have to work with the Spring MVC Test framework. It takes a bit to get up to speed, but it’s a really useful test framework. Initially, we were disappointed that we still had to document every single JSON field by hand and only got snippets for a cURL command, the HTTP request, and the HTTP response per test for free. Nevertheless, we were happy and continued using Spring REST docs.
Because the manual documentation of JSON fields stayed a pain point, we built an extensions that documented all JSON objects automatically by getting the structure and types via Jackson and the description from JavaDoc on the fields. In addition, we created modifiers that shortened the documented data by limiting JSON arrays to three elements and by replacing binary data with a short description. A lot more is possible here. Extending Spring REST Docs was greatly simplified with the release of 1.0.
Combining tests and documentation has the big advantage of keeping the automatically generated parts of the documentation up to date, because you’re forced to keep your tests up to date. Every time you see or touch the test you’re reminded of the documentation. This helps in keeping the manual parts of the documentation up to date. People are way more motivated to work on the documentation if the result is beautiful and consistent.
Too much coupling is usually a bad thing when programming, but coupling of code and documentation is definitely a good thing. Spring REST Docs allows us to store code and documentation in the same repository and deploy it together. This ensures that code and documentation do not diverge too much.
Not only the developers are happier, we also got lots of positive reactions from the consumers of the documentation. I’m thankful to my co-worker Juraj Misur who implemented the project together with me.
Update (2017–01–17): It’s open source now https://github.com/ScaCap/spring-auto-restdocs and available via Maven https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22capital.scalable%22
Update (2017–01–28): My co-worker Juraj Misur wrote an article about the release of this project — Spring Auto REST Docs: https://dzone.com/articles/introducing-spring-auto-rest-docs
