使用springdoc-openapi这个库来生成swagger的api文档
官方Github仓库： https://github.com/springdoc/springdoc-openapi
官网地址：https://springdoc.org
目录题
- 1. 引入依赖
- 2. 拦截器设置
- 3. 访问接口页面
- 3.1 添加配置项，使得访问路径变短（非必须）
- 4. 修改页面显示信息
- 5. 注解
1. 引入依赖
目前最新的版本是 springdoc-openapi v2.6.0。
然而 springdoc-openapi v1.8.0 是支持 Spring Boot 2.x 和 1.x 的最新开源版本。
而我的项目用的是 springboot 2.2.1 ，于是我就选择 1.8.0 的版本。
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.8.0</version>
</dependency>
大伙如果用的是 springboot 3 ，可以尝试使用最新版本的。
注意：SpringDoc不兼容swagger2的注解
2. 拦截器设置
如果项目中使用到了拦截器，那么就无法访问 http://localhost:8080/swagger-ui.html（端口号自行修改）
需要到 WebConfigurer 的 addInterceptors 方法中，排除swagger的路径
.excludePathPatterns("/swagger**/**","/**/api-docs/**")
或者这种写法
.excludePathPatterns("/swagger**/**")
.excludePathPatterns("/**/api-docs/**")
案例：
// 自定义拦截器JwtInterceptor，设置拦截规则
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(loginInterceptor)
.addPathPatterns("/**")
.excludePathPatterns("/login", "/register", "/files/**",
"/swagger**/**","/**/api-docs/**");
}
或者这样写
// 自定义拦截器JwtInterceptor，设置拦截规则
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(jwtInterceptor)
.addPathPatterns("/**")
.excludePathPatterns("/login")
.excludePathPatterns("/register")
.excludePathPatterns("/files/**")
// 排除swagger
.excludePathPatterns("/swagger**/**")
.excludePathPatterns("/**/api-docs/**")
;
}
3. 访问接口页面
配置好拦截器，重新启动，访问 http://localhost:8080/swagger-ui.html（端口号自行修改）
就可以看到如下画面，代表可以成功使用swagger了。
通过搜索框可以看到，访问路径是被重定向到 http://localhost:8080/v3/api-docs 。
所以排除的路径中，把包含swagger和api-docs的路径都排除了。
3.1 添加配置项，使得访问路径变短（非必须）
此时也可以在application.properties中添加一些配置，具体可以参考Spring Boot 整合 springdoc-openapi中的配置。
只加一行把/swagger-ui.html这个默认路径修改成比较方便访问的路径。
springdoc.swagger-ui.path=/api-docs
这样就变成了可以用 http://localhost:8080/api-docs 较短的路径来访问了。
4. 修改页面显示信息
| 基本信息注解 | 描述 | 可用于 | 属性 |
|---|---|---|---|
| @OpenAPIDefinition | 定义整个 API 文档的基本信息 | 类、接口 |
|
| @Info | 定义 API 文档的基本信息 | 类、接口 |
|
| @Contact | 定义 API 文档中的联系人信息 | 类、接口 |
|
| @License | 定义 API 文档中的许可证信息 | 类、接口 |
|
| @externalDocs | 定义 API 文档中的额外信息 | 类、接口 |
|
同样是在WebConfigurer中配置，添加如下代码：
@Bean
public OpenAPI openAPI(@Value("${springdoc.version}") String appVersion) {
return new OpenAPI()
.info(new Info() // ## API的基本信息，包括标题、版本号、描述、联系人等
.title("博客论坛系统 API") // Api接口文档标题（必填）
.description("博客论坛系统 前台用户和后台管理 API") // Api接口文档描述
.version(appVersion) // Api接口版本
.license(new License() // ## 联系人信息
.name("Apache2.0") // 授权名称
.url("http://springdoc.org")) // 授权信息
)
.contact(new Contact() // ## 作者信息
.name("奇妙方程式") // 作者名称
.email("229600398@qq.com") // 作者邮箱
.url("https://blog.csdn.net/weixin_45940369") // 介绍作者的URL地址
)
.externalDocs(new ExternalDocumentation() // ## API的额外信息
.description("文档") // 描述
.url("https://blog.csdn.net/weixin_45940369/article/details/141058944")); // 链接
}
这里配置了一个自定义的配置参数springdoc.version（也可以直接写成1.0），所以需要把这个加到application.properties中
springdoc.version=1.0
重新启动，查看页面
5. 注解
swagger2 和 swagger3 的注解的区别
| 用途 | swagger2 | swagger3 | 注解位置 | 案例 |
|---|---|---|---|---|
| 给 API 分组 | @Api | @Tag(name) | Controller类上 | @Tag(name = “活动管理”) |
| 描述 API 的操作 | @ApiOperation | @Operation(summary) | Controller方法上 | @Operation(summary = “新增活动接口”, description = “新增活动接口的说明”) |
| 描述操作的输入参数 | @ApiImplicitParams | @Parameters | Controller方法上 | |
| 描述操作的输入参数 | @ApiImplicitParam | @Parameter(description) | Controller方法上 | |
| 描述操作的输入参数 | @ApiParam | @Parameter(description) | Controller方法参数类上 | |
| 描述操作的输入参数 | @ApiIgnore | @Parameter(hidden=true) 或 @Operation(hidden=true) 或 @Hidden | 类或方法或参数上 | |
| 描述数据模型的属性 | @ApiModel | @Schema | 实体类上 | @Schema(title=“活动对象”, description=“活动对象的全部字段属性”) |
| 描述数据模型的属性 | @ApiModelProperty | @Schema | 实体类属性上 | @Schema(description = “活动id”, requiredMode = Schema.RequiredMode.REQUIRED, example = “1”) |
- title、name：名称
- description：描述
- requiredMode：指定该属性的必需性
Schema.RequiredMode.REQUIRED 表示这个属性是必需 - example：提供该属性的示例值
展示该属性的一个具体示例
参考文章
https://www.cnblogs.com/antLaddie/p/17418078.html
https://www.cnblogs.com/strongmore/p/18106597
https://www.jianshu.com/p/0c09b675c2d3
https://blog.csdn.net/weixin_59383491/article/details/135105646
