Spring REST Docs

Photo by Gabrielle Henderson on Unsplash

Overview

Without well-structured and accurate documentation/manual, there is nothing which is meaningful. Documentation/manuals help us to understand, and use each object in a proper way. Similarly, nowadays REST API(s) are playing a major role in software development orbit. So if there is no proper documentation for API, then the API will treat as a dead fish. Proper documentation acts as a reference point for anyone who wants to use our API(s).

Spring REST Docs produce documentation that is accurate, concise, and well structured. This documentation then allows your users to get the information they need with a minimum of fuss.

1. Advantages

The major philosophy behind this is it uses the tests to produce the documentation.

• It supports Hypermedia
• Always generated based on the tests which ensures that the documentation is always accurate and updated. If we update the test criteria, the documentation will get updated automatically.
• Supports both XML & JSON format.
• No need to add annotations and descriptions in controllers like Swagger.
• Supports both curl & HTTP.

2. Maven Dependencies

To enable the Spring REST Docs support, add spring-restdocs-mockmvc as an additional dependency in your application. We will use Spring-Boot for our example. The pom.xml will look like below

2.1 RESTful Service

Let’s create a REST Controller to expose some API(s).

3. Spring REST Docs Configuration

We will use the Spring MVC Test framework to write our unit test cases. Spring REST Docs use the test cases to generate accurate and updated documentation for the REST API.

3.1 Unit Test Case

We will test the HTTP request cycle in our Spring MVC application to make sure it is returning the expected value back to the client API.

3.2. Generating The Documentation

Once our test cases are ready, the next step is to generate the documentation for our API. This is where the Spring REST Docs provides the real advantages.

• The @AutoConfigureRestDocs takes as an argument a directory location for the generated snippets.
• The MockMvcRestDocumentation.documentfor the documentation location.

Now let's run the unit tests for your application . If all tests pass with no issue, it will generate a sub-folder under the target/snippets with a name matching the argument passed to the document method (in our case it is product/get-product-by-id). We will have several .adoc files.

3.3. Converting AsciiDoc to AsciiDoctor

One of the limitations with the AsciiDoc doc is that it is unable to render in the browser. So need to convert our AsciiDoc into a browser-friendly format like HTML. To convert our documentation into HTML format, we will use the AsciiDoctor maven plugin.

Get Debendra Dhinda’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

The updated pom.xml will look like below:

3.3. Joining the Generated Snippets

To make sure generated .adoc snippets and AsciiDoctor Maven plugin working together to generate the documentation, we need to glue together the generated .adoc files.

1. Create a directory src/main/asciidoc
2. Create a new file index.adoc under this new directory.

Add the below to our index.adoc :

Let’s run the mvn package command to generate the final HTML in the target/generated-docs folder. This is what our HTML file looks like:

Summary

Spring REST docs provide a lot of features and flexibility to generate documentation for your REST APIs. One of the powers of REST docs is its ability to generate the documentation based on the unit tests which ensure that documentation is accurate, concise, and well-structured. You can download the source code on GitHub

Read More

Best practice : REST API Resource Naming

Kafka — An Event Streaming Platform

SBA (Spring Boot Admin Server) — Monitoring and Management of Microservice