Spring Rest Docs With Spring Boot

Introduction

Spring REST Docs is a tool that helps you document your RESTful services. It combines the power of Asciidoctor with Spring MVC Test to produce documentation that is accurate and up-to-date. By integrating it with Spring Boot, you can easily set up your project to generate documentation for your APIs.

Setting Up Your Spring Boot Project

To get started, you'll need a Spring Boot project. You can create one using Spring Initializr or your preferred method. Ensure you include the following dependencies:

Dependencies:

Spring Web
Spring Boot DevTools
Spring REST Docs
Asciidoctor

Here’s how to add the necessary dependencies in your pom.xml if you're using Maven:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <version>2.0.6.RELEASE</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-spring-boot-starter</artifactId>
</dependency>

Creating a Simple REST API

Let’s create a simple REST API for managing books. First, create a Book model:

public class Book {
    private Long id;
    private String title;
    private String author;

    // Getters and Setters
}

Next, create a BookController to handle the HTTP requests:

@RestController
@RequestMapping("/api/books")
public class BookController {

    @GetMapping
    public List getBooks() {
        return Arrays.asList(new Book(1L, "1984", "George Orwell"),
                             new Book(2L, "To Kill a Mockingbird", "Harper Lee"));
    }
}

Configuring Spring REST Docs

Now, we need to configure Spring REST Docs in our test class. Create a test class for your controller:

@ExtendWith(SpringExtension.class)
@WebMvcTest(BookController.class)
public class BookControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private ObjectMapper objectMapper;

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

In this test, we use MockMvc to perform a GET request to our API. The document() method is used to generate the documentation snippets.

Generating Documentation

After running your tests, you will find the generated snippets in the target/generated-snippets directory. You can then use these snippets in your Asciidoctor files to create the final documentation.

Create an Asciidoctor file, for example, api-docs.adoc, and include the generated snippets:

Finally, you can generate the documentation by running the following command:

./mvnw clean package

Conclusion