#documentation

As development team we decided to write our documentation with Asciidoc. As other parts in our landscape use gradle as the build tool, thus we opted for the asciidoctor-gradle-plugin to generate the documentation. The documents have embedded plantuml diagrams describing the architecture, but to our surprise the toolchain did not render them correctly. Apparently the diagrams use features of plantuml that are not supported in the version provided by default by the toolchain.

We found out we had to update to later versions of asciidoctorj-diagram and plantuml. The version of asciidoctor-gradle-plugin (3.3.2) is now about a year old (from February 2021) and probably its dependencies also. Unfortunately it’s rather hard to find which versions are used by the asciidoctor-gradle plugin and how to update to newer versions.

Documenting spring restcontrollers with spring-restdocs is a sure way to get great documentation. It allows one to document API endpoints based on examples used in a test, and document specific fields in a response. It’s even possible to document additional attributes of a field in a JSON response.