In the previous tutorial, I showed you how to use the Springfox library to create RESTful API documentation according to OpenAPI specification in Spring Boot applications. But Springfox has been out of date for a long time and the springdoc-openapi library is updated continuously and has the same function as Springfox, so you should use the springdoc-openapi library from now on. In this tutorial, I will show you how to create RESTful API documentation with springdoc-openapi library in the Spring Boot application.
First, I will create a new Spring Boot project with Spring Web dependency as an example.
The result is as follows:
I will add Springdoc OpenAPI Starter WebMVC UI dependency as follows:
|
1 2 3 4 5 |
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.1.0</version> </dependency> |
If you are using Spring WebFlux, add the following dependency for it:
|
1 2 3 4 5 |
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webflux-ui</artifactId> <version>2.1.0</version> </dependency> |
Suppose now that I also have a controller that defines an API to manage student information simply as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
package com.huongdanjava.springboot; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping(value = "/student") public class StudentController { @GetMapping(value = "findById") public String findById(int id) { return "Khanh"; } } |
If you now run this Spring Boot application and access the address http://localhost:8080/swagger-ui/index.html, you will see the same result as when we use Springfox as follows:
By default, springdoc-openapi will scan all the controllers presented in our application to generate documents for the defined APIs.
Similar to the Docket class in Springfox, springdoc-openapi defines a GroupedOpenApi class that helps us configure information to generate API documentation, for example as follows:
|
1 2 3 4 5 6 7 8 |
@Bean GroupedOpenApi studentApi() { return GroupedOpenApi.builder() .group("Huong Dan Java") .packagesToScan("com.huongdanjava.springboot") .pathsToMatch("/student/*") .build(); } |
The “group” information is mandatory information you need to declare when defining beans using the GroupedOpenApi class. Similar to Springfox, springdoc-openapi also allows us to scan API filters by package or by context path.
As a result, you will see the “group” section will be displayed in the “Select a definition” field as follows:
You can use the Customizers classes located in the “org.springdoc.core.customizers” package of springdoc-openapi, to customize the API documentation the way you want.
For example, I want to change the title displayed for my group “Huong Dan Java” above from “OpenAPI definition” to “Student API”, I will add OpenApiCustomizer as follows:
|
1 2 3 4 5 6 7 8 9 |
@Bean GroupedOpenApi studentApi() { return GroupedOpenApi.builder() .group("Huong Dan Java") .packagesToScan("com.huongdanjava.springboot") .pathsToMatch("/student/*") .addOpenApiCustomizer(openApi -> openApi.info(new Info().title("Student API"))) .build(); } |
Result:
We can also customize the document for the API by adding some description about it, the return data, similar to Springfox.
Examples are as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
package com.huongdanjava.springboot; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.responses.ApiResponses; @RestController @RequestMapping(value = "/student") public class StudentController { @GetMapping(value = "findById") @Operation(summary = "Find student by id") @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "Success"), @ApiResponse(responseCode = "422", description = "Student not found"), @ApiResponse(responseCode = "417", description = "Exception failed") }) public String findById(int id) { return "Khanh"; } } |
The result is similar to when we use Springfox, guys:
