How to Document REST APIs in Spring Boot and Generate a Swagger API Website Automatically

Introduction

It’s a hard job to document your REST API in a traditional way that to keep a consistency of codes and documents outside codes. Here, I show you how to document your REST API closing to your source code in an annotation way. That’s awesome to back-end developers to make their work efficient and bugless to their documents.

Open API Specification v3.0 is a broadly adopted industry standard for describing modern APIs. You can learn how to work with it in Java way easily instead of learning its details.

1. Create a new Maven Project by Spring Initializr

Access the URL of Spring Initializr https://start.spring.io in your browser. And we need to add Spring Web library here.

Spring Initializr

Press Generate to download the project. In this guide, the project name is demo, therefore you can get a zip file named demo.zip. Unzip demo.zip and open the demo folder in your favorite editor or IDE to continue. In Visual Studio Code, it looks like:

Initialized Porject

2. Import springdoc-openapi Library

Springdoc-openapi is a vast library to document our APIs by annotations in the Spring project. You can understand it as an extension of Swagger to Spring.

Next, find the latest version of Springdoc-openapi library in Maven Repository Website and add to pom.xml.

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.3.7</version>
</dependency>

4. Create a Controller

Create a Java file named DemoController.java and add codes in it like this:

package com.example.demo;

import org.springframework.web.bind.annotation.RestController;

@RestController
public class DemoController {
}

5. Create a REST API

Add a member method into DemoController like this:

package com.example.demo;

import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;

@RestController
public class DemoController {
    @GetMapping(value = "/hello")
    public String helloBoy(@RequestParam String name) {
        return "Hello, " + name;
    }
}

6. Document the REST API

What to document for a API? I list some essential items:

  • Description
  • Parameters
  • Response Codes
  • Consumes (Content Types)
  • Produces (Accept Types)

And I document this API like this:

@Operation(description = "Say hello to some body!", responses = {
        @ApiResponse(responseCode = "200", content = @Content(
            schema = @Schema(implementation = String.class, example = "Hello, Jack"),
            mediaType = MediaType.TEXT_PLAIN_VALUE)) })
@GetMapping(value = "/hello")
public String helloBoy(@Parameter(description = "Boy's name") @RequestParam String name) {
    return "Hello, " + name;
}

@Operation is a method annotation. It contains many parameters, but not all parameters are required or essential. In this demo, I write a description for the API, and document the 200 response code including an example response and the media type of the response.

Besides, I document the only parameter name. In the argument list of helloBoy, you can use @Parameter annotation to document parameters of a API. The same as @Operation, @Parameter also have many parameters, and I will show you why I use springdoc-openapi instead of swagger. Springdoc-openapi can understand Spring annotations, and it means that springdoc-openapi can find the name of method/parameters and whether a parameter is required in this case. So we only need to add a description to the parameter in @Parameter annotation. I think it’s cool.

8. Run the Project

Run mvn spring-boot:run at the root directory of your project in your prompt.

9. Access the Document Website

Open the browser and access http://localhost:8080/swagger-ui.html.

OpenAPI 3 Document

Conclusion

Fewer configurations make developers focus on primary logic. Springdoc-api is growing, and Open API v3 is growing too. Writing document make developers think carefully on their codes and business. Therefore, it’s necessary to pay more attention to find a better way to evolve our workflow. You can find more details about Swagger and related annotations usage in https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations.