Micronaut Mastery: Documenting Our API Using Spring REST Docs

Spring REST Docs is a project to document a RESTful API using tests. The tests are used to invoke real REST calls on the application and to generate Asciidoctor markup snippets. We can use the generated snippets in an Asciidoctor document with documentation about our API. We can use Spring REST Docs to document a REST API we create using Micronaut.

First we must change our build file and include the Asciidoctor plugin and add dependencies to Spring REST Docs. The following example Gradle build file adds the Gradle Asciidoctor plugin, Spring REST Docs dependencies and configures the test and asciidoctor tasks. Spring REST Docs supports three different web clients to invoke the REST API of our application: Spring MockMVC, Spring Webflux WebTestClient and REST Assured. We use REST Assured 3, because it has little dependencies on other frameworks (like Spring).

Let’s add a controller to our application that has two methods to return one or more Conference objects. We want to document both REST API resource methods. First we look at the Conference class that is used:

Next we write the following controller to implement /conference to return multiple conferences and /conference/{name} to return a specific conference. The controller is dependent on the class ConferenceService that contains the real logic to get the data, but the implementation is not important for our example to document the controller:

Now it is time to write our test that will invoke our controller and generate Asciidoctor markup snippets. We use Spock for writing the test in our example:

Finally we create a Asciidoctor document to describe our API and use the generated Asciidoctor markup snippets from Spring REST Docs in our document. We rely in our example document on the operation macro that is part of Spring REST Docs to include some generated snippets:

We run the Gradle asciidoctor task to create the documentation. When we open the generated HTML we see the following result:

Written with Micronaut 1.0.0.M4 and Spring REST Docs 2.0.2.RELEASE.

Original post

This entry was posted in Asciidoctor, Coding, Micronaut and tagged , by mrhaki. Bookmark the permalink.

About mrhaki

My name is Hubert A. Klein Ikkink also known as mrhaki. I work at the great IT company JDriven. Here I work on projects with Groovy & Grails, Gradle and Spring. At JDriven we focus on SpringSource technologies. All colleagues want to learn new technologies, support craftmanship and are very eager to learn. This is truly a great environment to work in. You can contact me via Google+ or @mrhaki.

Leave a Reply

Your email address will not be published. Required fields are marked *