After I tried several ways to document my microservices I finally found a very easy one so that you can use your JavaDoc documentation together with your test code to produce nice to read HTML or PDF documents. The answer for me is Spring Auto REST Docs.
Other ways for documentation
In the beginning I tried swagger. This tool produces a great web site that offers easy access to all endpoints of your webservice and looks really good. What I’m missing is a document structures with an introduction where I can declare common rules how to use HTTP verbs and handle result codes. And I don’t like the necessity of adding a lot of annotations which will blow your code up.
Then I found RAML, the RESTful API Modeling Language. I was fascinated by the structured way of documenting the api and the possibility to reuse documentation snippets e.g. for data structures. But there was a standalone IDE for editing the documentation that could not be integrated in your favorite IDE. OK, if you want to define your REST interface first and then generate the source code, RAML is your friend. Unfortunately it does not offer an turn-around cycle where changes in the code are synchronized with the model.
My next try was Spring REST Docs. A very good idea to combine your (integration) tests with the api documentation. You can write a whole document with an introduction, a table of content, descriptions for every resource etc. Now you don’t miss any documentation part of an endpoint because you have 2 places to ask „what happens when the parameter value is wrong“ (test and documentation).
What all 3 documentation ways are missing is to use your JavaDoc. As I am writing frequently my JavaDoc why do I have to write it again in the API documentation? Copy-and-paste isn’t the answer!
When I found Spring Auto REST Docs I knew that this combines the most elegant und less redundant way to document my APIs. Here are the basic ideas:
- Generate JSON-snippets from the JavaDoc you wrote for entities and webservices.
- Use the information that Spring REST Docs gets from the test of your webservices.
- Combine these 2 into Asciidoctor-snippets and use them in an Asciidoctor document.
- The whole process is directed by Maven it is very easy to create the documentation in few seconds.
In the next blogs I want to show the details of this process. The next step is to have a look at the test code that is necessary for the documentation. Then I want to explain how Maven has to be configured to generate the document either as HTML or PDF. At least I try to explain how you have to use Asciidoctor to embed the snippets.
Enjoy this series of blogs.