SpringBoot 3.5 集成 Knife4j 4.3的詳細步驟
避坑指南：還在用 SpringFox？快換成這位“天選之子”吧！
各位小伙伴，有沒有遇到過這種讓人抓狂的場面：興沖沖地把 Spring Boot 2 升級到 Spring Boot 3，一啟動，嘿，項目跑起來了！正準備給自己點個贊，結果一打開 Swagger 頁面——404 空白。
這時候你才恍然大悟：原來當年陪我們渡過了無數(shù)個 CRUD 日夜的 SpringFox，早在 2020 年就悄悄停更了。它不僅跟不上 OpenAPI 3 的新潮規(guī)范，更致命的是，它底層死死抱住的 javax.* 包，在 Spring Boot 3 時代已經被徹底連根拔起，換成了 jakarta.* 。
簡單來說，這不是你代碼寫得有問題，而是時代的眼淚。面對這種“版本刺客”，硬剛肯定是不現(xiàn)實的。既然官宣分手，咱們就得收拾心情，尋找新的幸福——也就是今天的主角：SpringDoc。而 Knife4j 的底層就是SpringDoc。
為什么我說它是“天選之子”？
• 無縫銜接：它是基于 OpenAPI 3 規(guī)范量身定制的，對 Spring Boot 3 甚至 WebFlux 都是原生級支持，絲滑得就像德芙。
• 極簡主義：以前用 SpringFox 時，那一堆繁瑣的 Docket 配置是不是讓你很頭疼？換成 SpringDoc 后，很多時候你只需要引入一個 Starter 依賴，連配置文件都不用寫就能直接起飛。
• 社區(qū)活躍：不像前任那樣玩失蹤，SpringDoc 社區(qū)更新非?；钴S，遇到 Bug 也有人管，這才是長長久久的靠譜之選。
一、 核心組件與關系介紹
在微服務架構中，API 文檔工具通常分為“規(guī)范”、“生成器”和“展示層”三個部分。以下是它們的具體分工與關系：
組件 | 角色定位 | 核心作用 | 與 Knife4j 的關系 |
Swagger (OpenAPI 3) | 接口規(guī)范 | 定義了一套用于描述 API 接口的標準（如路徑、參數(shù)、返回值）。 | Knife4j 完全遵循 OpenAPI 3.0 規(guī)范生成文檔。 |
SpringDoc | 規(guī)范實現(xiàn) | 掃描 Spring Boot 代碼中的注解 （如 @Tag, @Operation） ，自動生成符合 OpenAPI 規(guī)范的 JSON 數(shù)據(jù)。 SpringDoc 自帶原生 Swagger UI。 | 底層依賴。Knife4j 4.x 已內置 SpringDoc，負責數(shù)據(jù)的生產。 |
Knife4j | UI 增強層 | 基于 SpringDoc 提供的數(shù)據(jù)，渲染出美觀、交互性更強的文檔界面。 | 上層封裝。在 SpringDoc 基礎上提供了文檔增強、離線導出等功能。 |
二、 Knife4j 簡介與資源
Knife4j 是一個為 Java MVC 框架集成 Swagger 生成 API 文檔的增強解決方案。其前身是 swagger-bootstrap-ui，旨在提供更符合國人習慣的接口文檔體驗。
- 核心作用：
- 文檔說明：根據(jù)代碼注解自動生成詳盡的接口文檔，包含請求/響應示例。
- 在線調試：提供強大的接口調試功能，支持全局參數(shù)、動態(tài)參數(shù)修改。
- 離線文檔：支持導出 Markdown、HTML、Word 等格式的離線文檔，方便交付。
- 界面優(yōu)化：提供現(xiàn)代化的 UI 界面，支持深色模式、接口搜索與排序。
- 官方資源：
三、 Spring Boot 3.5 單體應用集成步驟
1. 環(huán)境準備
- JDK：17 及以上（Spring Boot 3.x 強制要求）
- Spring Boot：3.5.9
- Knife4j：4.3.0
2. 引入 Maven 依賴
在 pom.xml 中添加 Knife4j 的 Starter。該依賴已內置 SpringDoc，無需再單獨引入 Swagger 相關包。
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>依賴包 knife4j-openapi3-jakarta-spring-boot-starter 包含子依賴包主要有:
依賴包 | 描述 | 核心作用 |
knife4j-openapi3-ui | Knife4j 的 UI 核心 | 提供增強的 Web 界面 (/doc.html)，包含文檔渲染、接口調試、全局參數(shù)、離線導出等功能。 |
knife4j-core | Knife4j 工具模塊 | 提供工具類、模型定義、核心工具鏈等底層支持。 |
springdoc-openapi-starter-webmvc-ui | SpringDoc WebMVC 集成與 UI | 提供原生的 Swagger UI (/swagger-ui.html)，是 SpringDoc 自動配置的入口。 |
springdoc-openapi-starter-webmvc-api | SpringDoc WebMvc API 支持 | 提供對 Spring WebMVC 的底層支持，包含請求/響應處理、參數(shù)解析等。 |
springdoc-openapi-starter-webmvc-common | SpringDoc WebMvc 通用模塊 | 包含 SpringDoc 的通用工具類和核心邏輯，是 API 模塊的基礎。 |
swagger-annotations-jakarta | OpenAPI 注解庫 (Jakarta) | 提供 jakarta命名空間版本的 OpenAPI 注解，如 @Tag, @Operation, @Schema等。 |
swagger-models-jakarta | OpenAPI 模型庫 (Jakarta) | 提供 jakarta命名空間版本的 OpenAPI 數(shù)據(jù)模型，如 Info, Contact, OpenAPI等。 |
swagger-ui | Swagger UI 前端資源 | 包含 Swagger UI 的所有前端靜態(tài)資源（HTML, JS, CSS），被 springdoc-openapi-starter-webmvc-ui所依賴。 |
3. 配置文件 (application.yml)
配置 SpringDoc 的掃描規(guī)則和 Knife4j 的增強特性。
# SpringDoc 原生配置
springdoc:
swagger-ui:
enabled: true
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
enabled: true
path: /v3/api-docs
group-configs:
- group: default
paths-to-match: '/**'
packages-to-scan: com.example.controller
# Knife4j 增強配置
knife4j:
enable: true
setting:
language: zh_cn
enable-swagger-models: true
swagger-model-name: 實體類列表4. 初始化配置 @Configuration
/**
* OpenApi3在線接口文檔組件初始化
*/
@Slf4j
@Configuration(proxyBeanMethods = false)
@ConditionalOnProperty(name = "springdoc.api-docs.enabled", matchIfMissing = true)
public class OpenApi3Config {
@Bean
public OpenAPI springDocOpenAPI() {
return new OpenAPI(SpecVersion.V30).info(new Info()
.title("API文檔")
.description("簡介")
.version("v1.0"))
// 配置Authorizations
.components(new Components()
.addSecuritySchemes("Authorization", new SecurityScheme().name("Authorization").in(SecurityScheme.In.HEADER).type(SecurityScheme.Type.APIKEY))
.addSecuritySchemes("TenandId", new SecurityScheme().name("TenandId").in(SecurityScheme.In.HEADER).type(SecurityScheme.Type.APIKEY)));
}
}5. 注解示例
Spring Boot 3.x 使用 OpenAPI 3 規(guī)范注解，與舊版 Swagger 2 不同。
注解 | 作用位置 | 描述 | 示例/替代舊注解 |
@Tag | Controller 類 | API 分組標簽 | 替代 @Api |
@Operation | Controller 方法 | 單個接口的詳細描述 | 替代 @ApiOperation |
@Parameter | 方法參數(shù) | 描述單個參數(shù) | 替代 @ApiParam |
@Schema | 模型類/字段 | 描述數(shù)據(jù)模型/字段 | 替代 @ApiModel, @ApiModelProperty |
@Parameters | 方法 | 多個參數(shù)的容器 | 包含多個 @Parameter |
控制器Controller
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
@RestController
@RequestMapping("/api/users")
@Tag(name = "用戶管理")
public class UserController {
@GetMapping("/{id}")
@Operation(summary = "根據(jù)ID查詢用戶")
public String getUser(@Parameter(description = "用戶ID", required = true) @PathVariable Long id) {
return "User " + id;
}
}實體Bean
@Schema(description = "用戶信息")
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class UserInfo {
/**
* 中文名
*/
@Schema(description = "中文名")
private String name;
}6 訪問驗證
啟動項目后，訪問以下地址：
- Knife4j 文檔地址：http://localhost:8080/doc.html
- 原生 Swagger 地址：http://localhost:8080/swagger-ui.html
效果圖
四、 Spring Cloud Gateway 集成方案
在微服務架構中，通常希望在網(wǎng)關層聚合所有微服務的接口文檔，無需逐個訪問子服務。
1. 網(wǎng)關服務 (Gateway) 配置
在 Gateway 模塊中引入聚合依賴：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-gateway-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>
<!-- 這里特別注意，只能引入 springdoc-openapi-starter-webflux-api ，
不要引入 springdoc-openapi-starter-webflux-ui,
不然在 doc.html 會出現(xiàn)微服務下拉列表無法獲取數(shù)據(jù) -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webflux-api</artifactId>
<version>2.8.15</version>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
<version>4.3.3</version>
</dependency>在 application.yml 中開啟服務發(fā)現(xiàn)模式聚合：
# 第二種配置方式：自動發(fā)現(xiàn)
knife4j:
gateway:
enabled: true
# 指定聚合模式為服務發(fā)現(xiàn)（基于注冊中心如 Nacos/Eureka）
strategy: discover
discover:
enabled: true
version: openapi3
# 第二種配置方式：手動配置
knife4j:
gateway:
enabled: true
strategy: manual
operations-sorter: order
routes:
- name: 用戶服務
context-path: /user
url: /user/v3/api-docs/default
- name: 訂單管理
context-path: /order
url: /order/v3/api-docs/default2. 子微服務 (Service) 配置
確保每個業(yè)務微服務都按照 第三部分 的步驟引入了 knife4j-openapi3-jakarta-spring-boot-starter 并正確配置了 packages-to-scan。
3. 訪問方式
啟動網(wǎng)關和各個微服務后，直接訪問 網(wǎng)關的地址 即可查看聚合文檔：
http://網(wǎng)關IP:網(wǎng)關端口/doc.html
效果圖
到此這篇關于SpringBoot 3.5 集成 Knife4j 4.3的詳細步驟的文章就介紹到這了,更多相關SpringBoot 集成 Knife4j內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！
- SpringBoot集成Knife4j/Swagger:接口文檔自動生成,告別手寫API文檔
- springboot升級到3.5.x后knife4j文檔無法識別問題及解決過程
- SpringBoot中使用Knife4j生成接口文檔的示例詳解
- springboot+knife4j+nacos實踐
- knife4j+springboot3.4異常無法正確展示文檔
- Springboot3集成Knife4j的步驟以及使用(最完整版)
- SpringBoot?Knife4j框架&Knife4j的顯示內容的配置方式
- SpringBoot與knife4j的整合使用過程
- springboot集成swagger、knife4j及常用注解的使用
相關文章
這篇文章主要介紹了SpringBoot自動裝配原理的相關資料，幫助大家更好的理解和學習使用SpringBoot框架，感興趣的朋友可以了解下2021-03-03
在Java中創(chuàng)建JSON字符串,我們可以使用多個庫,其中最流行的是Jackson、Gson和org.json,,下面給大家分享Java設置JSON字符串參數(shù)編碼的示例,感興趣的朋友一起看看吧2024-06-06
Gradle進階使用結合Sonarqube進行代碼審查的方法
今天小編就為大家分享一篇關于Gradle進階使用結合Sonarqube進行代碼審查的方法，小編覺得內容挺不錯的，現(xiàn)在分享給大家，具有很好的參考價值，需要的朋友一起跟隨小編來看看吧2018-12-12
SpringBoot整合spring-data-jpa的方法
這篇文章主要介紹了SpringBoot整合spring-data-jpa的方法，本文通過實例代碼給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值,需要的朋友可以參考下2020-06-06
這篇文章主要介紹了mybatis一直加載xml，找到錯誤的解決方案，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-02-02
MyBatis-Plus攔截器實現(xiàn)數(shù)據(jù)權限控制的方法
MyBatis-Plus是一款基于MyBatis的增強工具,它提供了一些便捷的功能和增強的查詢能力,數(shù)據(jù)權限控制是在系統(tǒng)中對用戶訪問數(shù)據(jù)進行限制的一種機制,這篇文章主要給大家介紹了關于MyBatis-Plus攔截器實現(xiàn)數(shù)據(jù)權限控制的相關資料,需要的朋友可以參考下2024-01-01
適配器模式，即將某個類的接口轉換成客戶端期望的另一個接口的表示，主要目的是實現(xiàn)兼容性，讓原本因為接口不匹配，沒辦法一起工作的兩個類，可以協(xié)同工作。本文將通過示例詳細介紹適配器模式，需要的可以參考一下2022-02-02
這篇文章主要給大家分享的是SpringBoot攔截器的使用，攔截器通常通過動態(tài)代理的方式來執(zhí)行。攔截器的生命周期由IoC容器管理，可以通過注入等方式來獲取其他Bean的實例，使用更方便，下面文章的詳細內容,需要的朋友可以參考一下2021-11-11
MyBatis TypeHandler自定義類型轉換與實戰(zhàn)案例解析
本文將介紹MyBatis中TypeHandler的基礎概念,并通過具體的使用案例,展示如何自定義并應用TypeHandler以提高數(shù)據(jù)處理的靈活性和可維護性,感興趣的朋友跟隨小編一起看看吧2026-01-01
這篇文章主要介紹了SpringBoot之使用枚舉參數(shù)案例詳解,本篇文章通過簡要的案例,講解了該項技術的了解與使用,以下就是詳細內容,需要的朋友可以參考下2021-09-09