Spring Boot integrates SpringDoc Swagger 3

background

Spring boot has been updated to v2.6+. If you are still using Springfox to provide swagger interface documentation, you will encounter the following error:

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
    ...
Caused by: java.lang.NullPointerException: null
    at springfox.documentation.spring.web.WebMvcPatternsRequestConditionWrapper.getPatterns(WebMvcPatternsRequestConditionWrapper.java:56) ~[springfox-spring-webmvc-3.0.0.jar:3.0.0]
    at springfox.documentation.RequestHandler.sortedPaths(RequestHandler.java:113) ~[springfox-core-3.0.0.jar:3.0.0]

The update speed of Springfox is too slow. In order to adapt to the new version of Spring boot, replacing it with SpringDoc is a better choice.

Configure and integrate SpringDoc to implement swagger interface documentation

Step 1. Introduce SpringDoc dependency

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

Step 2. Add configuration class

// 示例配置类
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI initOpenAPI() {
        return new OpenAPI().info(
            new Info().title("My Project API").description("OpenAPI").version("v1.0")
        );
    }
}

Steps 1 & 2 are the normal configuration of swagger. If the system has a security check of the interface URL, you need to configure the following interface to allow anonymous access so that the swagger related url can be accessed.
Step 3. Set the anonymous url configuration related to swagger to as follows:

/swagger**/**
/v3/**

If the diboot-IAM component is used, the relevant configuration examples are as follows:

diboot.iam.anon-urls=/swagger**/**,/v3/**

swagger3 related annotations

Annotations added to Controller classes and methods (@Tag & @Operation):

import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;

//...
@Tag(name = "用户接口", description = "用户相关CRUD接口")
public class UserController{
    
    @Operation(summary = "获取用户列表数据")
    @GetMapping("/list")
    public JsonResult getViewObjectListMapping() throws Exception{
        //...
    }
}

Annotations added to Entity/Model classes and attributes (@Schema):

import io.swagger.v3.oas.annotations.media.Schema;
import java.io.Serializable;

@Schema(name = "用户", description = "用户实体定义")
public class User implements Serializable {
    private static final long serialVersionUID = 111222L;
    /**
     * 名称 
     */
    @Schema(description = "名称", required = true, example = "张三")
    private String name;
}

Swagger interface document access entry address:

• Swagger interface document entry address: /(contextPath)/swagger-ui.html

The example effect is as follows:

Other common configurations

Specify the interface package path

Add the following configuration to specify the interface scan package path:

springdoc.packages-to-scan=com.example

Disable swagger in production environment

Add the following configuration and close the interface document:

springdoc.api-docs.enabled=false

---

diboot Simple and efficient low-code development framework