SpringBoot 生成Swagger接口文档

半塘 2024/1/25 SpringBoot 框架

项目开发中，接口文档是必不可少的，无论是对接还是交付，都需要接口文档。本章需要了解 OpenAPI 规范、Swagger3、SpringDoc、Swagger UI、knife4j，以及ApiPost接口测试工具。

# 1、OpenAPI 规范

参考：OpenAPI 规范 (中文版) (opens new window)

OpenAPI 规范（OAS），是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好，那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。

如果您遵循 OpenAPI 规范来定义您的 API，那么您就可以用文档生成工具来展示您的 API，用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码，用自动测试工具进行测试等等。

# 2、Swagger

# 2.1、Swagger简介

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。它可以帮助开发人员快速创建强大的API，并提供了文档生成和API管理的功能。Swagger通过注解的方式，将接口文档化，并且能够直接进行接口调用和测试，降低了项目开发阶段的调试成本。总体目标是使客户端和文件系统作为服务器以同样的速度来更新，使API始终保持同步。

# 2.2、Swagger UI

Swagger UI是HTML，Javascript和CSS资产的集合，可以从符合OAS标准的API动态生成漂亮的文档。

# 3、配置Swagger

SpringBoot3只支持OpenAPI3规范，Swagger3已经迁移到Springdoc。

Swagger3、springfox、springdoc的关系

Swagger3（或OpenAPI 3.x）是一个API描述规范，而Springfox和Springdoc是实现了这一规范的工具库，用于在Spring应用程序中自动生成API文档。
Springfox在早期的Swagger 2.0时代非常受欢迎，并且后来也支持了OpenAPI 3.0。然而，由于一些用户反馈和社区活动，Springdoc在某些方面可能被视为一个更现代、更活跃的选择，特别是对于需要OpenAPI 3.0支持的项目。

# 3.1、引入依赖

<!-- Swagger3 （引入springdoc）官方建议是springdoc替代springfox-->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.0.2</version>
</dependency>
<!-- Swagger UI -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>

1
2
3
4
5
6
7
8
9
10
11
12

# 3.2、配置SwaggerConfig

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("SpringBoot-Study")
                        .description("Swagger API文档")
                        .version("v1")
                        .license(new License().name("星云系导航").url("https://www.xygalaxy.com/")))
                .externalDocs(new ExternalDocumentation()
                        .description("全栈知识体系")
                        .url("https://blog.xygalaxy.com/"));
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 3.3、配置application.yml

#springdoc相关配置
springdoc:
  swagger-ui:
    #自定义swagger前端请求路径，输入http：127.0.0.1:8080/swagger-ui.html会自动重定向到swagger页面
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs    #swagger后端请求地址
    enabled: true   #是否开启文档功能
  group-configs:
    - group: 'com.xygalaxy'
      paths-to-match: '/**'
      packages-to-scan: com.xygalaxy    #按包路径匹配:一般到启动类的包名

1
2
3
4
5
6
7
8
9
10
11
12
13
14

springdoc全部配置说明

springdoc:
  # OpenAPI文档相关参数
  api-docs:
    # OpenAPI文档开关, true: 开启OpenAPI文档访问功能, false: 关闭。
    enabled: true       
    # JSON格式的OpenAPI文档的访问路径
    path: /v3/api-docs
  # 扫描哪些包来生成OpenAPI文档, 多个包名用逗号分隔
  packages-to-scan: * 
  # 路径匹配规则, API路径符合这些匹配规则才会包含到OpenAPI文档中, 多个规则用逗号分隔
  paths-to-match: /* 
  # 返回媒体类型匹配规则, 返回媒体类型符合这些匹配规则才会包含到OpenAPI文档中, 多个规则用逗号分隔
  produces-to-match: /* 
  # 请求头匹配规则, 请求头符合这些匹配规则才会包含到OpenAPI文档中, 多个规则用逗号分隔
  headers-to-match: /* 
  # 请求媒体类型匹配规则, 请求媒体类型符合这些匹配规则才会包含到OpenAPI文档中, 多个规则用逗号分隔
  consumes-to-match: /* 
  # 排除路径匹配规则, API路径符合这些匹配规则会排除在OpenAPI文档之外, 多个规则用逗号分隔
  paths-to-exclude: 
  # 排除包匹配规则, 包名符合这些匹配规则会排除在OpenAPI文档之外, 多个规则用逗号分隔
  packages-to-exclude: 
  # 默认请求媒体类型
  default-consumes-media-type: application/json
  # 默认返回的响应媒体类型
  default-produces-media-type: '*/*' 
  # 是否禁用OpenAPI文档缓存, 
  # 禁用后每次访问${springdoc.api-docs.path}都会重新生成(适合开发调试阶段)当响应会比较缓慢。
  cache.disabled: false 
  # 是否显示Spring Actuator的接口
  show-actuator: false 
  # 是否自动将类名生成为Tag
  auto-tag-classes: true 
  # 是否包含返回ModelAndView对象的接口
  model-and-view-allowed: false 
  # 是否从 @ControllerAdvice 注解获取接口的响应信息.
  override-with-generic-response: true 
  # 是否开启接口分组功能, 开启后, 一个App可以生成多个OpenAPI文档, 每个文档显示一部分接口。
  api-docs.groups.enabled: true 
  # 分组配置
  group-configs:
      # 分组名称
    - group: XXX
      # 同`springdoc.packages-to-scan`
      packages-to-scan: *    
      # 同`springdoc.paths-to-match`
      paths-to-match: /*     
      # 同`springdoc.paths-to-exclude`
      paths-to-exclude: ``   
      # 同`springdoc.packages-to-exclude`
      packages-to-exclude:   
      # 同`springdoc.produces-to-match`
      produces-to-match: /*  
      # 同`springdoc.consumes-to-match`
      consumes-to-match: /*  
      # 同`springdoc.headers-to-match`
      headers-to-match: /* 
  # webjar资源的访问路径前缀
  webjars.prefix: /webjars 
  # 是否翻译属性值, true: Schema中的属性的值可以用Spring的表达式来编写, 然后运行时自动转成真实的取值
  api-docs.resolve-schema-properties: false 
  # 删除无效的引用定义
  remove-broken-reference-definitions: true 
  # 是否格式化输出的OpenAPI文档, 方便人类阅读
  writer-with-default-pretty-printer: false 
  # 是否启用 deprecating model converter.
  model-converters.deprecating-converter.enabled: true 
  # 生成的Schema等组件的名称是否使用全名(类似java的Class.getName和getSimpleName的区别)
  use-fqn: false # FQN是指 fully qualified names.
  # 是否显示spring security的登录接口
  show-login-endpoint: false
  # 是否预加载OpenAPI文档, true: 程序启动的时候就生成OpenAPI文档, false: 第一次访问OpenAPI文档的时候生成。
  pre-loading-enabled: false

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

# 3.4、使用注解配置接口

swagger3 注解代替 swagger2，因为改动太大，故 springfox对旧版的 swagger做了兼容处理。也就是两种注解都可以用。但springdoc好像只能支持swagger3。

不知道未来会不会不兼容，建议都可以使用试试。

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属性上

@RestController
@RequestMapping("/student")
@Slf4j
@Tag(name = "学生控制层",description = "学生信息查询")
public class StudentController {

    @Operation(summary ="查询所有学生")
    @GetMapping("/list2")
    public ResponseResult<List<StudentPO>> userList2(){
        return ResponseResult.success(studentService.list());
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13

# 3.5、测试swagger

http://localhost:8080/swagger-ui.html

访问页面

测试使用

# 4、配置Knife4J

虽然Swagger UI页面可以用，但其实并不友好，所以我们可以再集成一个Knife4J文档。(不想集成可以看看ApiPost)

Knife4J是一款基于Swagger快速生成API文档和调试平台的开源工具，它可以轻松地将Swagger规范转换成易于阅读的文档，并支持在线测试API。Knife4J内置了多种主题和插件，提供了丰富的样式和功能配置，可以自定义API文档的展示方式和内容。

# 4.1、引入依赖

<!--基于knife4j-openapi3的api接口文档生成-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

1
2
3
4
5
6

# 4.2、配置application.yml

#knife4j相关配置 可以不用改
knife4j:
  enable: true    #开启knife4j，无需添加@EnableKnife4j注解
  setting:
    language: zh_cn   #中文
    swagger-model-name: 实体类   #重命名SwaggerModel名称,默认
  #开启Swagger的Basic认证功能,默认是false
#  basic:
#    enable: true
    # Basic认证用户名
#    username: xygalaxy
#    # Basic认证密码
#    password: xygalaxy

1
2
3
4
5
6
7
8
9
10
11
12
13

# 4.3、Knife4J测试访问

http://127.0.0.1:8080/doc.html

Knife4J访问并调试

# 5、Swagger配合ApiPost

ApiPost (opens new window)、Apifox (opens new window)是两款比较流行的测试工具，当然最开始大家比较常用的还是PostMan (opens new window)，不过还是与时俱进，用用新工具。直接去官网下载就可以了。这里用ApiPost演示一下怎么配合Swagger使用。