Spring Boot 集成 SpringDoc Swagger 3

背景

Spring boot 已经更新到了 v2.6+，如果你还在使用Springfox提供swagger接口文档，你会遇到以下错误：

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]

Springfox的更新速度太慢了，为了适配新版本Spring boot，将其替换为SpringDoc是个更优的选择。

配置集成 SpringDoc 实现 swagger接口文档

步骤1. pom中引入SpringDoc依赖

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

步骤2. 添加配置类

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

步骤1&2为swagger的正常配置，如果系统有接口URL的安全检查，需要将以下接口配置为允许匿名访问，以使swagger相关url可以访问到。
步骤3. 设置swagger相关的匿名url配置，使swagger不被拦截， 如下：

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

如果使用了diboot-IAM组件，相关配置示例如下:

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

swagger3 相关注解说明

加在Controller类及方法上的注解 （@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{
        //...
    }
}

加在Entity/Model类及属性上的注解 （@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 接口文档访问入口地址:

• swagger接口文档入口地址: /{contextPath}/swagger-ui.html

示例效果如图：

其他常用配置

指定接口包路径

添加以下配置，指定接口扫描package包路径：

springdoc.packages-to-scan=com.example

生产环境禁用swagger

添加以下配置，关闭接口文档：

springdoc.api-docs.enabled=false

---

diboot 简单高效的低代码开发框架