# Spring Boot 集成 SpringDoc Swagger 3
author: diboot team , publish date: 2021.11.23
# 背景
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]
1
2
3
4
5
2
3
4
5
Springfox的更新速度太慢了，为了适配新版本Spring boot，将其替换为SpringDoc是个更优的选择。
# 配置集成 SpringDoc 实现 swagger接口文档
步骤1. pom中引入SpringDoc依赖
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.3</version>
</dependency>
1
2
3
4
5
2
3
4
5
步骤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
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
步骤1&2为swagger的正常配置，如果系统有接口URL的安全检查，需要将以下接口配置为允许匿名访问，以使swagger相关url可以访问到。 步骤3. 设置swagger相关的匿名url配置，使swagger不被拦截， 如下：
/swagger**/**
/v3/**
1
2
2
如果使用了diboot-IAM组件，相关配置示例如下:
diboot.iam.anon-urls=/swagger**/**,/v3/**
1
# 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{
//...
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
# 加在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;
}
1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
# swagger 接口文档访问入口地址:
- swagger接口文档入口地址: /{contextPath}/swagger-ui.html
示例效果如图：
# 其他常用配置
# 指定接口包路径
添加以下配置，指定接口扫描package包路径：
springdoc.packages-to-scan=com.example
1
# 生产环境禁用swagger
添加以下配置，关闭接口文档：
springdoc.api-docs.enabled=false
1
# swagger v2 -> swagger v3 注解对应
| swagger2 | OpenAPI 3 | 注解加在哪 |
|---|---|---|
| @Api | @Tag(name = “接口类描述”) | Controller 类上 |
| @ApiOperation | @Operation(summary =“接口方法描述”) | Controller 方法上 |
| @ApiImplicitParams | @Parameters | Controller 方法上 |
| @ApiImplicitParam | @Parameter(description=“参数描述”) | Controller 方法上 @Parameters 里 |
| @ApiParam | @Parameter(description=“参数描述”) | Controller 方法的参数上 |
| @ApiIgnore | @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden | - |
| @ApiModel | @Schema | DTO类上 |
| @ApiModelProperty | @Schema | DTO属性上 |