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: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

注解：

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

注解：

1. 使用 @Configuration 注解标记该类为配置类。
2. OpenAPI.info()：配置文档的基本信息。
3. 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();
    }
}

注解：

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.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

注解：

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 文档。