Spring Boot 3 + SpringDoc：打造接口文档

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"));}
}

注解：

1. 使用 @RestController 注解标记该类为一个 REST 控制器。
2. @RequestMapping(“/api/programmer”) 定义了该控制器的路径前缀。
3. @PostMapping() 和 @GetMapping(“/{id}”) 分别定义了创建程序员和获取程序员的接口路径。

4.2 配置 SpringDoc
4.2.1 使用 YAML 配置
我们可以通过 YAML 文件对 SpringDoc 进行详细配置，例如：

springdoc:api-docs:enabled:trueswagger-ui:persistAuthorization:true
info:title:'程序员管理系统 API 文档'description:'用于管理程序员信息的系统'version:'v1.0'contact:name:张三email:[e-mail]:https://example.com
components:security-schemes:apiKey:type:APIKEYin:HEADERname:Authorization
group-configs:-group:程序员管理packages-to-scan: com.example.programmer

注解：

1. springdoc.api-docs.enabled：启用 API 文档。
2. springdoc.info.*：配置文档的基本信息，如标题、描述、版本和联系人信息。
3. springdoc.components.security-schemes：定义安全认证方式，如 API 密钥。
4. springdoc.group-configs：按包路径对 API 进行分组。

4.2.2 使用 Java 配置
除了 YAML 配置，我们还可以通过 Java 代码进行更灵活的配置。

例如：

@Configuration
public class SpringDocConfig {@Beanpublic OpenAPI myOpenAPI() {returnnewOpenAPI().info(newInfo().title("程序员管理系统 API").description("用于管理程序员信息").version("v1.0").contact(newContact().name("张三").email("[e-mail]"))).externalDocs(newExternalDocumentation().description("项目主页").url("https://example.com"));}
}

注解：

1. 使用 @Configuration 注解标记该类为配置类。
2. OpenAPI.info()：配置文档的基本信息。
3. OpenAPI.externalDocs()：添加外部文档链接。

4.3 配置文档分组
如果项目中有多个模块，我们可以将 API 按模块分组。

例如：

@Configuration
public class SpringDocConfig {@Beanpublic GroupedOpenApi programmerApi() {return GroupedOpenApi.builder().group("程序员管理").pathsToMatch("/api/programmer/**").build();}@Beanpublic GroupedOpenApi adminApi() {return GroupedOpenApi.builder().group("管理员模块").pathsToMatch("/api/admin/**").build();}
}

注解：

1. 使用 GroupedOpenApi.builder() 创建分组。
2. 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"));}
}

注解：

1. @Tag：为整个控制器添加模块描述。
2. @Operation：为每个接口方法添加详细描述。
3. @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.htmltags-sorter:alphaoperations-sorter:alpha
api-docs:path:/v3/api-docs
group-configs:-group:'默认分组'paths-to-match:'/**'packages-to-scan:com.example.demoknife4j:
enable:true
setting:language: zh_cn

注解：

1. springdoc.swagger-ui.path：指定 Swagger UI 的访问路径。
2. knife4j.enable：启用 Knife4j 功能。
3. knife4j.setting.language：设置文档语言。
4. 使用 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"));}
}

注解：

1. 使用 @Tag 和 @Operation 注解描述控制器和接口。
2. 使用 @Parameter 注解描述方法参数。

访问 http://localhost:8080/doc.html 即可查看 Knife4j 提供的增强版 API 文档。