Unofficial tutorial of SpringBoot Part 10: creating API document "suggestions collection" with Spring Restdocs

Posted by gregghealy on Mon, 07 Mar 2022 04:49:14 +0100

Hello, everyone. Meet again. I'm Jun Quan.


You need 15 min
Jdk 1.8
maven 3.0+

Create project

Import dependency, and its pom file:




Start springboot through @ SpringBootApplication

public class Application {

    public static void main(String[] args) {, args);

A controller is usually created in springboot:

public class HomeController {

    public Map<String, Object> greeting() {
        return Collections.singletonMap("message", "Hello World");


Start the project, visit localhost:8080, and the browser displays:

{"message":"Hello World"}

Prove that the interface has been written, but how to survive api documents through restdoc

Restdoc, generating api documents through unit tests

restdocs survives snippets files through unit tests, and then snippets generates htm documents according to plug-ins.

Create a unit test class:

@AutoConfigureRestDocs(outputDir = "target/snippets")
public class WebLayerTest {

    private MockMvc mockMvc;

    public void shouldReturnDefaultMessage() throws Exception {
                .andExpect(content().string(containsString("Hello World")))

The @ AutoConfigureRestDocs annotation enables the generation of snippets files and specifies the storage location.

Start the unit test and pass the test. You will find that a snippets folder is generated under the target file. Its directory structure is as follows:

└── target
    └── snippets
        └── home
            └── httpie-request.adoc
            └── curl-request.adoc
            └── http-request.adoc
            └── http-response.adoc

By default, snippets are files in ASCII locator format, including request and reply, and the other two popular command-line http request modes, httpie and curl.

So far, only Snippets files have been generated, and documents need to be generated with Snippets files.

How to use Snippets

Create a new file Src / main / ASCII Doc / index adoc :

Building documents with Spring REST Docs

This is an example output for a service running at http://localhost:8080:



This example is very simple. You can get the api document through unit test and some simple configuration.

For the writing format of adoc, refer to: , I won't explain much here.

You need to use the asciidoctor Maven plugin plug-in and add the following to its pom file:


At this time, you only need to use the mvnw package command to generate documents. There is an index under / target / generated docs html, open this html, the display is as follows, and the interface is relatively simple:


Through the unit test, you can save the ADO file, and then use the ADO file to save the html. In a few simple steps, you can generate an html file of api document, which you can publish through the website. The whole process is simple and has no impact on the code.

Source code download:

Publisher: full stack programmer, stack length, please indicate the source for Reprint: Original link: