1、背景公司
新项目使用SpringBoot3.0以上构建，其中需要对外输出接口文档。接口文档一方面给到前端调试，另一方面给到测试使用。
2、SpringDoc 是什么？
SpringDoc 是一个基于 Spring Boot 项目的库，能够自动根据项目中的配置、类结构和注解生成 API 文档。
它遵循 OpenAPI 3 规范，通过检查运行中的程序，推断出 API 的语义，并以 JSON、YAML 和 HTML 格式输出文档。
这与我们熟知的 Swagger 项目有着紧密的联系。
Swagger 作为 OpenAPI 规范的前身，贡献了其 API 设计理念并促成了 OpenAPI 的标准化。
而 Springfox，作为 Swagger 的具体实现，曾在行业中占据主导地位，但自 2020 年停止更新后，逐渐被 SpringDoc 所取代。
SpringDoc 不仅支持最新的 OpenAPI 3 规范，还完美兼容 Spring Boot 3，成为新项目的首选工具。
3、核心概念
OpenAPI：是一个组织（OpenAPI Initiative），他们指定了如何描述HTTP API的规范（OpenAPI Specification）。既然是规范，那么谁想实现都可以，只要符合规范即可。
Swagger：它是SmartBear这个公司的一个开源项目，里面提供了一系列工具，包括著名的 swagger-ui。swagger是早于OpenApi的，某一天swagger将自己的API设计贡献给了OpenApi，然后由其标准化了。
Springfox：是Spring生态的一个开源库，是Swagger与OpenApi规范的具体实现。我们使用它就可以在spring中生成API文档。以前基本上是行业标准，目前最新版本可以支持 Swagger2, Swagger3 以及 OpenAPI3 三种格式。但是其从 2020年7月14号就不再更新了，不支持springboot3，所以业界都在不断的转向另一个库Springdoc。
SpringDoc：算是后起之秀，带着继任Springfox的使命而来。其支持OpenApi规范，支持Springboot3。
4、使用方法
4.1 简单集成
在 Spring Boot 项目中集成 SpringDoc 非常简单，只需在 pom.xml 文件中添加以下依赖即可：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.8.6</version>
</dependency>
运行项目后，访问 http://localhost:8080/swagger-ui.html 即可查看自动生成的 API 文档。
例如，我们有以下简单的控制器代码：。
@RestController
@RequestMapping("/api/programmer")
publicclassProgrammerController {
@PostMapping()
public Programmer createProgrammer(@RequestBody CreateProgrammerRequest request) {
returnnewProgrammer(1, request.getAge(), request.getProgrammingLang());
}
@GetMapping("/{id}")
public Programmer getProgrammer(@PathVariable Integer id) {
returnnewProgrammer(1, 35, List.of("Java", "Python", "SQL"));
}
}
注解：
- 使用 @RestController 注解标记该类为一个 REST 控制器。
- @RequestMapping(“/api/programmer”) 定义了该控制器的路径前缀。
- @PostMapping() 和 @GetMapping(“/{id}”) 分别定义了创建程序员和获取程序员的接口路径。
4.2 配置 SpringDoc
4.2.1 使用 YAML 配置
我们可以通过 YAML 文件对 SpringDoc 进行详细配置，例如：
springdoc:
api-docs:
enabled:true
swagger-ui:
persistAuthorization:true
info:
title:'程序员管理系统 API 文档'
description:'用于管理程序员信息的系统'
version:'v1.0'
contact:
name:张三
email:zhangsan@example.com
url:https://example.com
components:
security-schemes:
apiKey:
type:APIKEY
in:HEADER
name:Authorization
group-configs:
-group:程序员管理
packages-to-scan: com.example.programmer
注解：
- springdoc.api-docs.enabled：启用 API 文档。
- springdoc.info.*：配置文档的基本信息，如标题、描述、版本和联系人信息。
- springdoc.components.security-schemes：定义安全认证方式，如 API 密钥。
- springdoc.group-configs：按包路径对 API 进行分组。
4.2.2 使用 Java 配置
除了 YAML 配置，我们还可以通过 Java 代码进行更灵活的配置。
例如：
@Configuration
public class SpringDocConfig {
@Bean
public OpenAPI myOpenAPI() {
returnnewOpenAPI()
.info(newInfo()
.title("程序员管理系统 API")
.description("用于管理程序员信息")
.version("v1.0")
.contact(newContact()
.name("张三")
.email("zhangsan@example.com")))
.externalDocs(newExternalDocumentation()
.description("项目主页")
.url("https://example.com"));
}
}
注解：
- 使用 @Configuration 注解标记该类为配置类。
- OpenAPI.info()：配置文档的基本信息。
- OpenAPI.externalDocs()：添加外部文档链接。
4.3 配置文档分组
如果项目中有多个模块，我们可以将 API 按模块分组。
例如：
@Configuration
public class SpringDocConfig {
@Bean
public GroupedOpenApi programmerApi() {
return GroupedOpenApi.builder()
.group("程序员管理")
.pathsToMatch("/api/programmer/**")
.build();
}
@Bean
public GroupedOpenApi adminApi() {
return GroupedOpenApi.builder()
.group("管理员模块")
.pathsToMatch("/api/admin/**")
.build();
}
}
注解：
- 使用 GroupedOpenApi.builder() 创建分组。
- pathsToMatch：指定该分组匹配的路径。
4.4 注解
SpringDoc 提供了丰富的注解来描述 API 的各个部分，以下是一些常用的注解：
• @Tag：用于控制器类，描述模块信息。
• @Operation：用于控制器方法，描述接口信息。
• @Parameter：用于方法参数，描述参数信息。
• @Schema：用于实体类及其属性，描述数据结构。
• @ApiResponse：用于描述接口的返回值。
例如：
@Tag(name = "程序员管理", description = "管理程序员信息")
@RestController
@RequestMapping("/api/programmer")
public class ProgrammerController {
@Operation(summary = "创建程序员", description = "创建一个新的程序员")
@PostMapping()
public Programmer createProgrammer(@RequestBody CreateProgrammerRequest request) {
returnnewProgrammer(1, request.getAge(), request.getProgrammingLang());
}
@Operation(summary = "获取程序员信息", description = "根据 ID 获取程序员信息")
@GetMapping("/{id}")
public Programmer getProgrammer(@Parameter(description = "程序员 ID") @PathVariable Integer id) {
returnnewProgrammer(1, 35, List.of("Java", "Python", "SQL"));
}
}
注解：
- @Tag：为整个控制器添加模块描述。
- @Operation：为每个接口方法添加详细描述。
- @Parameter：为方法参数添加描述。
SpringDoc 与 Knife4j 的整合
Knife4j 是一个增强版的 API 文档工具，它提供了更美观的 UI 和更多的功能。
SpringDoc 可以与 Knife4j 无缝整合，为开发者提供更好的体验。
5 1. Knife4j 的前世今生
Knife4j 前身是 swagger-bootstrap-ui，经过多次迭代，逐渐发展成为一个基于 Vue 和 Ant Design 的现代化 UI 工具。
它支持 OpenAPI 3 规范，并提供了丰富的功能，如分组管理、接口排序等。
5 2. Spring Boot 版本兼容性
Knife4j 提供了多个版本，以适配不同版本的 Spring Boot。
1. 添加依赖：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.5.0</version>
</dependency>
2. 配置 Knife4j：
springdoc:
swagger-ui:
path:/swagger-ui.html
tags-sorter:alpha
operations-sorter:alpha
api-docs:
path:/v3/api-docs
group-configs:
-group:'默认分组'
paths-to-match:'/**'
packages-to-scan:com.example.demo
knife4j:
enable:true
setting:
language: zh_cn
注解：
- springdoc.swagger-ui.path：指定 Swagger UI 的访问路径。
- knife4j.enable：启用 Knife4j 功能。
- knife4j.setting.language：设置文档语言。
- 使用 OpenAPI 3 规范注解：
@RestController
@RequestMapping("/api/programmer")
@Tag(name = "程序员管理", description = "管理程序员信息")
public class ProgrammerController {
@Operation(summary = "创建程序员", description = "创建一个新的程序员")
@PostMapping()
public Programmer createProgrammer(@RequestBody CreateProgrammerRequest request) {
returnnewProgrammer(1, request.getAge(), request.getProgrammingLang());
}
@Operation(summary = "获取程序员信息", description = "根据 ID 获取程序员信息")
@GetMapping("/{id}")
public Programmer getProgrammer(@Parameter(description = "程序员 ID") @PathVariable Integer id) {
returnnewProgrammer(1, 35, List.of("Java", "Python", "SQL"));
}
}
注解：
- 使用 @Tag 和 @Operation 注解描述控制器和接口。
- 使用 @Parameter 注解描述方法参数。
访问 http://localhost:8080/doc.html 即可查看 Knife4j 提供的增强版 API 文档。
![STM32单片机入门学习——第41节: [12-1] Unix时间戳](https://i-blog.csdnimg.cn/direct/563422f697e143de96d0797bd40be6c6.png)
