API Documentation with springdoc-openapi

OpenAPI Initiative is a widely adopted industry standard to describe and document APIs, with Swagger being one of its most well-known implementations. For years, Springfox, using Swagger, has provided a well-adopted toolchain for Spring projects to generate OpenAPI documentation and provide a UI on the top of it. Unfortunately, the Springfox project is not frequently maintained; its latest release v2.9.2 at the timing of writing this post was in 2018. This is where springdoc-openapi comes into the picture.

Springdoc is a relatively young open-source project that adds several new features not available in Springfox at the moment, including the support for OpenAPI Specification 3 (OAS 3) and functional and reactive Spring APIs to create REST endpoints. In this post, we'll explore how we can use Springdoc with a Spring Boot project.

You can run an instance of Postgres by installing it on your machine or in the cloud. For a Docker container, use the following Compose file.

 1version: '3'
 2
 3services:
 4  db:
 5    image: postgres:13-alpine
 6    container_name: pg13
 7    restart: always
 8    ports:
 9      - 5432:5432
10    environment:
11      POSTGRES_USER: erin
12      POSTGRES_PASSWORD: richards

Execute the following command to launch the container.

docker-compose up -d

Springdoc with Spring WebMvc

Generate a Spring Boot project using Spring Initializr, and add spring-boot-starter-web, spring-boot-starter-data-jdbc, postgresql, and spring-boot-starter-actuator dependencies. Your pom.xml would look like this.

 1<?xml version="1.0" encoding="UTF-8"?>
 2<project xmlns="http://maven.apache.org/POM/4.0.0"
 3  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 4  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 5  <modelVersion>4.0.0</modelVersion>
 6
 7  <parent>
 8    <groupId>org.springframework.boot</groupId>
 9    <artifactId>spring-boot-starter-parent</artifactId>
10    <version>2.3.1.RELEASE</version>
11    <relativePath/> <!-- lookup parent from repository -->
12  </parent>
13
14  <groupId>dev.mflash.guides</groupId>
15  <artifactId>springdoc-integration</artifactId>
16  <version>0.0.1-SNAPSHOT</version>
17
18  <properties>
19    <java.version>14</java.version>
20  </properties>
21
22  <dependencies>
23    <dependency>
24      <groupId>org.springframework.boot</groupId>
25      <artifactId>spring-boot-starter-web</artifactId>
26    </dependency>
27
28    <dependency>
29      <groupId>org.springframework.boot</groupId>
30      <artifactId>spring-boot-starter-data-jdbc</artifactId>
31    </dependency>
32    <dependency>
33      <groupId>org.postgresql</groupId>
34      <artifactId>postgresql</artifactId>
35      <scope>runtime</scope>
36    </dependency>
37
38    <dependency>
39      <groupId>org.springframework.boot</groupId>
40      <artifactId>spring-boot-starter-actuator</artifactId>
41    </dependency>
42
43    <dependency>
44      <groupId>org.springframework.boot</groupId>
45      <artifactId>spring-boot-starter-test</artifactId>
46      <scope>test</scope>
47      <exclusions>
48        <exclusion>
49          <groupId>org.junit.vintage</groupId>
50          <artifactId>junit-vintage-engine</artifactId>
51        </exclusion>
52      </exclusions>
53    </dependency>
54  </dependencies>
55
56  <build>
57    <plugins>
58      <plugin>
59        <groupId>org.springframework.boot</groupId>
60        <artifactId>spring-boot-maven-plugin</artifactId>
61      </plugin>
62    </plugins>
63  </build>
64
65</project>

Rename application.properties to application.yml, open it in an editor, and add the following configuration (change it wherever required).

1# src/main/resources/application.yml
2
3spring:
4  datasource:
5    platform: postgres
6    url: jdbc:postgresql://localhost:5432/spring
7    username: erin
8    password: richards

Create some endpoints

Let's quickly create some endpoints. Say we want to save a Note object in a Postgres relation defined by the following statement.

1CREATE TABLE note (
2  id SERIAL PRIMARY KEY,
3  title TEXT,
4  content TEXT
5);

Define an entity for this relation as follows.

 1// src/main/java/dev/mflash/guides/springdoc/Note.java
 2
 3public class Note {
 4
 5  private @Id long id;
 6  private String title;
 7  private String content;
 8
 9  // getters, setters, etc
10}

The id will be automatically generated by a Postgres sequence that gets created with the CREATE statement above which specifies the id field to be of SERIAL type.

Create a repository to perform CRUD operations with the Note entity.

1// src/main/java/dev/mflash/guides/springdoc/NoteRepository.java
2
3public interface NoteRepository extends CrudRepository<Note, Long> {
4
5}

Expose some of the CRUD operations through a controller.

 1// src/main/java/dev/mflash/guides/springdoc/NoteController.java
 2
 3@RestController
 4@RequestMapping("/note")
 5public class NoteController {
 6
 7  private final NoteRepository repository;
 8
 9  public NoteController(NoteRepository repository) {
10    this.repository = repository;
11  }
12
13  @PutMapping
14  public List<Note> save(@RequestBody List<Note> notes) {
15    List<Note> savedNotes = new ArrayList<>();
16    repository.saveAll(notes).forEach(savedNotes::add);
17    return savedNotes;
18  }
19
20  @GetMapping
21  public List<Note> findAll() {
22    List<Note> savedNotes = new ArrayList<>();
23    repository.findAll().forEach(savedNotes::add);
24    return savedNotes;
25  }
26
27  @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
28  public List<Note> upload(@RequestParam("data") MultipartFile csv) throws IOException {
29    List<Note> savedNotes = new ArrayList<>();
30    List<Note> notes = new BufferedReader(
31        new InputStreamReader(Objects.requireNonNull(csv).getInputStream(), StandardCharsets.UTF_8)).lines()
32        .map(Note::parseNote).collect(Collectors.toList());
33    repository.saveAll(notes).forEach(savedNotes::add);
34    return savedNotes;
35  }
36
37  @DeleteMapping("/{id}")
38  public boolean delete(@PathVariable("id") long id) {
39    repository.deleteById(id);
40    return true;
41  }
42}

Here, apart from the usual endpoints, we also want to upload a CSV of notes and persist them in the database; a functionality exposed through the upload method.

Integrating Springdoc

Add the following dependency in the pom.xml.

1<dependency>
2  <groupId>org.springdoc</groupId>
3  <artifactId>springdoc-openapi-ui</artifactId>
4  <version>1.4.3</version>
5</dependency>

Add a @Tag to NoteController to describe it.

1// src/main/java/dev/mflash/guides/springdoc/NoteController.java
2
3@Tag(name = "Note", description = "Endpoints for CRUD operations on notes")
4public class NoteController {
5
6  // rest of the code
7}

To add some metadata, inject a bean returning an OpenAPI object.

 1// src/main/java/dev/mflash/guides/springdoc/Launcher.java
 2
 3public @SpringBootApplication class Launcher {
 4
 5  public static void main(String[] args) {
 6    SpringApplication.run(Launcher.class, args);
 7  }
 8
 9  public @Bean OpenAPI noteAPI() {
10    return new OpenAPI()
11        .info(
12            new Info()
13                .title("Note API")
14                .description("A CRUD API to demonstrate Springdoc integration")
15                .version("0.0.1-SNAPSHOT")
16                .license(
17                    new License().name("MIT").url("https://opensource.org/licenses/MIT")
18                )
19        );
20  }
21}

Launch the application and open http://localhost:8080/swagger-ui.html. You'd see the Swagger UI with the endpoints exposed by NoteController.

You can also access the OpenAPI docs at http://localhost:8080/v3/api-docs which can be imported in tools like Postman, Insomnia, etc.

Springdoc with Spring WebMvc.fn

To work with Spring's functional endpoint API, some refactoring is required so that Springdoc can infer the API contracts. Create a NoteService and the following code.

 1// src/main/java/dev/mflash/guides/springdoc/NoteService.java
 2
 3@Tag(name = "Note", description = "Endpoints for CRUD operations on notes")
 4public @Service class NoteService {
 5
 6  private final NoteRepository repository;
 7
 8  public NoteService(NoteRepository repository) {
 9    this.repository = repository;
10  }
11
12  public List<Note> save(List<Note> notes) {
13    List<Note> savedNotes = new ArrayList<>();
14    repository.saveAll(notes).forEach(savedNotes::add);
15    return savedNotes;
16  }
17
18  public List<Note> findAll() {
19    List<Note> savedNotes = new ArrayList<>();
20    repository.findAll().forEach(savedNotes::add);
21    return savedNotes;
22  }
23
24  public List<Note> upload(Part csv) throws IOException {
25    List<Note> savedNotes = new ArrayList<>();
26    List<Note> notes = new BufferedReader(
27        new InputStreamReader(csv.getInputStream(), StandardCharsets.UTF_8)).lines()
28        .map(Note::parseNote).collect(Collectors.toList());
29    repository.saveAll(notes).forEach(savedNotes::add);
30    return savedNotes;
31  }
32
33  public boolean delete(@Parameter(in = ParameterIn.PATH) long id) {
34    repository.deleteById(id);
35    return true;
36  }
37}

Note that

• the @Tag annotation is now applied on the service
• a Swagger-specific @Parameter annotation is used to specify that id is a path variable to the delete method

Refactor the controller using Spring's functional API.

 1// src/main/java/dev/mflash/guides/springdoc/NoteController.java
 2
 3public @Controller class NoteController {
 4
 5  private final NoteService service;
 6
 7  public NoteController(NoteService service) {
 8    this.service = service;
 9  }
10
11  public ServerResponse save(ServerRequest request) throws ServletException, IOException {
12    final List<Note> newNotes = request.body(new ParameterizedTypeReference<>() {});
13    return ServerResponse.ok().contentType(APPLICATION_JSON).body(service.save(newNotes));
14  }
15
16  public ServerResponse findAll(ServerRequest request) {
17    return ServerResponse.ok().contentType(APPLICATION_JSON).body(service.findAll());
18  }
19
20  public ServerResponse upload(ServerRequest request) throws IOException, ServletException {
21    Part csv = request.servletRequest().getPart("data");
22    return ServerResponse.ok().contentType(APPLICATION_JSON).body(service.upload(csv));
23  }
24
25  public ServerResponse delete(ServerRequest request) {
26    long id = Long.parseLong(request.pathVariable("id"));
27    return ServerResponse.ok().contentType(APPLICATION_JSON).body(service.delete(id));
28  }
29
30  @RouterOperations({
31    @RouterOperation(path = "/note", method = PUT, beanClass = NoteService.class, beanMethod = "save"),
32    @RouterOperation(path = "/note", method = GET, beanClass = NoteService.class, beanMethod = "findAll"),
33    @RouterOperation(path = "/note", method = POST,
34        operation = @Operation(
35            operationId = "multipart-upload",
36            requestBody = @RequestBody(required = true, description = "Upload a csv of notes"),
37            responses = @ApiResponse()
38        ),
39        beanClass = NoteService.class, beanMethod = "upload"),
40    @RouterOperation(path = "/note/{id}", method = DELETE, beanClass = NoteService.class, beanMethod = "delete")
41  })
42  public @Bean RouterFunction<ServerResponse> routes() {
43    return route()
44        .nest(RequestPredicates.path("/note"),
45            builder -> builder.PUT("/", this::save)
46                .GET("/", this::findAll)
47                .POST("/", RequestPredicates.accept(MULTIPART_FORM_DATA), this::upload)
48                .DELETE("/{id}", this::delete).build())
49        .build();
50  }
51}

Note that the controller is annotated with @Controller, instead of @RestController (why? 🤔). The interesting part is at the router configuration method routes.

Springdoc provides @RouterOperation annotation for a single-route configuration and @RouterOperations annotation for multiple-route configuration (which is the case for the above example). Note that the beanClass and beanMethod are necessary to allow Springdoc inspect NoteService and resolve the API contracts. Furthermore, for a multipart upload, we need to specify an @Operation with a unique id and provide a customization to let Springdoc know that it is a multipart upload operation. This can be done by injecting an OpenApiCustomiser bean as follows.

 1// src/main/java/dev/mflash/guides/springdoc/Launcher.java
 2
 3public @SpringBootApplication class Launcher {
 4
 5  public static void main(String[] args) {
 6    SpringApplication.run(Launcher.class, args);
 7  }
 8
 9  public @Bean OpenAPI noteAPI() {
10    return new OpenAPI()
11        .info(
12            new Info()
13                .title("Note API")
14                .description("A CRUD API to demonstrate Springdoc integration")
15                .version("0.0.1-SNAPSHOT")
16                .license(
17                    new License().name("MIT").url("https://opensource.org/licenses/MIT")
18                )
19        );
20  }
21
22  public @Bean OpenApiCustomiser openApiCustomiser() {
23    return openApi -> openApi.getPaths()
24        .values().stream().flatMap(pathItem -> pathItem.readOperations().stream())
25        .forEach(operation -> {
26          if ("multipart-upload".equals(operation.getOperationId())) {
27            operation.getRequestBody()
28                .setContent(
29                    new Content().addMediaType(
30                        MediaType.MULTIPART_FORM_DATA_VALUE,
31                        new io.swagger.v3.oas.models.media.MediaType()
32                            .schema(new ObjectSchema().addProperties("data", new FileSchema()))
33                    )
34                );
35          }
36        });
37  }
38}

Once again, launch the application and open http://localhost:8080/swagger-ui.html to access the Swagger UI.

References

Source Code — springdoc-webmvc-integration, springdoc-webmvcfn-integration

Related

• Springdoc documentation