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:zhangsan@example.comurl: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("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 {@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 文檔。