API Documentation with Springfox 3

Table of contents

Springfox 3 with Spring WebMvc

Recently, the popular Springfox project released the long-awaited v3 of their library with support for OpenAPI 3 and Spring 5 (only annotation-based API is supported). It also comes with a ready-to-use Spring Boot starter which replaces a host of dependencies that were required in earlier versions. This version fills a lot of gaps that another project springdoc-openapi had addressed for a while.

In this post, we’ll explore similar usecases that we’d covered in an earlier post on springdoc-openapi.

To run Postgres in a Docker container, use the following Compose file.

yaml

 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

Springfox 3 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.

xml

 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.3.RELEASE</version>
11    <relativePath/> <!-- lookup parent from repository -->
12  </parent>
13
14  <groupId>dev.mflash.guides</groupId>
15  <artifactId>springfox3-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).

yml

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 create some endpoints that we can show in the documentation. Say, we want to create a CRUD API for a Note object in a Postgres relation defined by the following statement.

sql

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

Define an entity for this relation as follows.

java

 1// src/main/java/dev/mflash/guides/springfox3/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}

Postgres will generate the id automatically when a save operation is performed since the id field is of SERIAL type.

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

java

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

Expose some of the CRUD operations through a controller.

java

 1// src/main/java/dev/mflash/guides/springfox3/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 other endpoints, we’ve exposed an endpoint, through the upload method, to upload a CSV of notes and persist them in the database.

Integrating Springfox 3

Add the Springfox Boot Starter in the pom.xml.

xml

1<dependency>
2  <groupId>io.springfox</groupId>
3  <artifactId>springfox-boot-starter</artifactId>
4  <version>3.0.0</version>
5</dependency>

Annotate the NoteController with a @Tag annotation. This is not required but using a tag, we can provide a description for the controller with the Docket API later.

java

1// src/main/java/dev/mflash/guides/springfox3/NoteController.java
2
3@Api(tags = "Note")
4public class NoteController {
5
6  // rest of the code
7}

Customize the metadata and the description of the above controller by injecting a Docket bean.

java

 1// src/main/java/dev/mflash/guides/springfox3/Launcher.java
 2
 3public @SpringBootApplication class Launcher {
 4
 5  public static void main(String[] args) {
 6    SpringApplication.run(Launcher.class, args);
 7  }
 8
 9  @Bean
10  public Docket docket() {
11    return new Docket(DocumentationType.OAS_30)
12        .apiInfo(new ApiInfoBuilder()
13            .title("Note API")
14            .description("A CRUD API to demonstrate Springfox 3 integration")
15            .version("0.0.1-SNAPSHOT")
16            .license("MIT")
17            .licenseUrl("https://opensource.org/licenses/MIT")
18            .build())
19        .tags(new Tag("Note", "Endpoints for CRUD operations on notes"))
20        .select().apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
21        .build();
22  }
23}

Launch the application and visit http://localhost:8080/swagger-ui/ where you’ll see the documentation on the endpoints exposed by NoteController.

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

References

Source code

springfox3-webmvc-integration