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.
It’s great to have Asciidoc labels like swagger-ui in the documentation, but would it be possible to extend this even further? In asciidoc documentation I also use Plantuml diagrams, e.g. to illustrate the sequence of interaction between microservices. Is it possible to label those interactions like swagger-ui, just as I now can in asciidoc?
If you’re building a rest api with spring-boot and want to document the api, you have two good options to do this; Springfox, or Spring REST Docs. Springfox creates (interactive) documentation through a swagger-ui to use by a developer, Spring REST Docs creates documentation via asciidoc. And what’s best is that you can simply combine the two in a project.