Introduction to Spring REST Docs

What is Spring REST Docs?

Spring REST Docs is a tool that helps you create documentation for your RESTful services. It produces documentation snippets that can be included in your project’s documentation, ensuring that your API documentation is accurate and up-to-date with the actual implementation.

Why Use Spring REST Docs?

There are several reasons to use Spring REST Docs:

• Automated Documentation: It generates documentation based on your tests, meaning your documentation is always in sync with your API.
• Customizability: You can customize the documentation to fit your needs and style.
• Integration: It integrates elegantly with Spring MVC.
• Support for Asciidoctor: It works well with Asciidoctor to produce beautiful documentation in multiple formats.

Getting Started with Spring REST Docs

To get started with Spring REST Docs, you need to add the necessary dependencies to your project. Below is an example of how to do this using Maven.

    
        org.springframework.restdocs
        spring-restdocs-mockmvc
        2.0.6.RELEASE
        test
    
    
        org.springframework.boot
        spring-boot-starter-test
        test
    

                

Creating Documentation Snippets

After adding the dependencies, you can start writing tests for your REST controllers while generating documentation snippets. Below is an example of how to write a test that generates documentation for a simple REST API.

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.*;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.mockmvc.RestDocumentationMockMvcConfigurer;
import org.springframework.test.web.servlet.MockMvc;

@WebMvcTest
@AutoConfigureRestDocs
public class MyControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void testGetEndpoint() throws Exception {
        this.mockMvc.perform(get("/api/my-endpoint"))
                .andExpect(status().isOk())
                .andDo(document("my-endpoint"));
    }
}
                

Generating the Documentation

Once you have written your tests, you can run them to generate the snippets. The generated snippets will be stored in a directory specified in your configuration.

Typically, the documentation is generated in a generated-snippets directory. You can include these snippets in your Asciidoctor documentation files.

Integrating with Asciidoctor

To include the generated snippets in your Asciidoctor documentation, you can use the following syntax in your .adoc files:

include::{snippets}/my-endpoint.json[]
                

This will include the generated JSON snippet for your endpoint in the documentation.

Conclusion

Spring REST Docs is a powerful tool for documenting REST APIs. By integrating it into your testing process, you can ensure that your documentation is always in sync with your code. This not only helps in providing accurate documentation but also improves the overall quality of your API.