告別SwaggerUI！一款更適合SpringBoot的API文檔新選擇！

作者：儒猿團(tuán)隊 2025-08-20 09:34:57

經(jīng)過社區(qū)的大浪淘沙，目前最適合 SpringBoot 生態(tài)的 API 文檔解決方案已經(jīng)浮出水面：SpringDoc + Knife4j的黃金組合。

兄弟們，我們每天都在和各種 "輪子" 打交道，而 API 文檔工具絕對是其中最讓人又愛又恨的存在。今天咱們就來聊一個程序員圈內(nèi)的 "老大難" 問題：API 文檔工具的選擇。如果你也曾被 SwaggerUI 的迷之界面折磨過，被版本沖突搞得焦頭爛額，或者看著前端同學(xué)拿著接口文檔一臉迷茫，那這篇文章你可算來對地方了！

那些年我們踩過的 SwaggerUI 坑

先聲明：SwaggerUI 作為 API 文檔工具的先行者，絕對是有功之臣。但就像十年前的諾基亞神機(jī)，再好也架不住時代發(fā)展啊！咱們來細(xì)數(shù)一下 SwaggerUI 的那些 "槽點"，看看你中了幾條：

界面審美疲勞：默認(rèn)界面堪稱 "復(fù)古風(fēng)" 典范，黑白灰的配色方案讓看文檔變成了苦差事。前端同學(xué)經(jīng)常吐槽："這界面比我的代碼還丑，看著就沒調(diào)接口的欲望"。

版本兼容性噩夢：升級 SpringBoot 到 2.6.x 之后，Swagger2 直接罷工；好不容易換成 Swagger3，又發(fā)現(xiàn)各種注解不兼容。更別說升級到 SpringBoot 3.x 之后，那簡直是災(zāi)難現(xiàn)場 —— 各種 ClassNotFoundException 層出不窮。

注解冗余問題：為了生成像樣的文檔，代碼里塞滿了 @Api、@ApiOperation、@ApiModel 等注解，有時候注解比業(yè)務(wù)代碼還多，嚴(yán)重影響可讀性。

功能局限性：想導(dǎo)出離線文檔？想做接口分組？想自定義文檔首頁？對不起，要么沒有要么得自己擼代碼擴(kuò)展。最尷尬的是調(diào)試復(fù)雜參數(shù)時，界面經(jīng)常錯亂，還不如 Postman 來得實在。

性能拖后腿：啟動時掃描所有接口，大項目能明顯感覺到啟動變慢。有次線上緊急發(fā)版，就因為 Swagger 的掃描耗時過長，差點錯過了最佳發(fā)布窗口。

如果你也遇到過這些問題，別慌，不是你一個人在戰(zhàn)斗！這不是你的錯，也不是 SwaggerUI 的錯，只能說它們的 "緣分已盡"—— 尤其是在 SpringBoot 版本不斷迭代的今天，我們需要更合拍的新選擇。

新選擇登場：SpringDoc + Knife4j 組合

經(jīng)過社區(qū)的大浪淘沙，目前最適合 SpringBoot 生態(tài)的 API 文檔解決方案已經(jīng)浮出水面：SpringDoc + Knife4j的黃金組合。簡單說，這倆的關(guān)系就像 "地基" 和 "精裝修"——SpringDoc 負(fù)責(zé)底層的 API 文檔生成，遵循最新的 OpenAPI 3 規(guī)范；Knife4j 則在其基礎(chǔ)上做了 UI 增強(qiáng)和功能擴(kuò)展，讓文檔既好用又好看。

為啥說它們更適合 SpringBoot 呢？咱們直接上對比表：

特性	SwaggerUI(SpringFox)	SpringDoc + Knife4j
規(guī)范支持	Swagger 2.0 為主	完全支持 OpenAPI 3.0+
SpringBoot 3.x 兼容	不支持	完美支持
啟動速度	較慢（掃描機(jī)制老舊）	更快（優(yōu)化的掃描邏輯）
UI 界面	簡陋復(fù)古	現(xiàn)代美觀，支持深色模式
注解復(fù)雜度	高（專屬注解多）	低（兼容 JSR303 規(guī)范）
擴(kuò)展功能	有限	豐富（離線文檔、接口排序等）
社區(qū)活躍度	低（基本停更）	高（持續(xù)迭代）

看到這里可能有同學(xué)會問："我直接用 SpringDoc 自帶的 Swagger UI 不行嗎？為啥還要加個 Knife4j？" 問得好！這就好比買了毛坯房雖然能住，但刷個墻、鋪個地板不是更舒服嗎？Knife4j 就是那個能把 "毛坯房" 變成 "精裝房" 的存在。

實戰(zhàn)操作：從零開始集成

光說不練假把式，接下來咱們就手把手教大家如何在 SpringBoot 項目中集成這套 "黃金組合"。考慮到現(xiàn)在 SpringBoot 3.x 已經(jīng)成為主流，咱們就以最新的版本為例進(jìn)行演示。

第一步：清理舊依賴（重要！）

如果你之前用過 Swagger/SpringFox，第一步必須是徹底清理舊依賴，否則會出現(xiàn)各種沖突。打開你的 pom.xml（或 build.gradle），把這些統(tǒng)統(tǒng)刪掉：

<!-- 舊的Swagger/SpringFox依賴，全部移除 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

最好再執(zhí)行一下依賴清理命令，確保沒有殘留：

# Maven
mvn dependency:purge-local-repository -Dinclude=springfox*
# Gradle
gradle clean build --refresh-dependencies

這一步千萬別偷懶！很多同學(xué)集成失敗都是因為舊依賴沒清理干凈，導(dǎo)致 Bean 沖突或者類找不到。

第二步：引入新依賴

根據(jù)你的 SpringBoot 版本選擇對應(yīng)的依賴組合，這是官方推薦的 "黃金搭配"：

SpringBoot 版本	SpringDoc 版本	Knife4j 版本
3.0.x - 3.2.x	2.5.x	4.3.x
3.3.x - 3.4.x	2.6.x（或 SNAPSHOT）	4.4.x

以 SpringBoot 3.2.x 為例，在 pom.xml 中添加：

<!-- SpringDoc核心依賴 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>
<!-- Knife4j增強(qiáng)UI -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

注意：如果你用的是 SpringBoot 3.x，一定要選擇帶 "jakarta" 的 Knife4j 依賴，因為 SpringBoot 3.x 已經(jīng)全面采用 Jakarta EE 規(guī)范了。

第三步：基礎(chǔ)配置

添加一個配置類，用于自定義 API 文檔的基本信息：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                // 文檔基本信息
                .info(new Info()
                        .title("用戶管理系統(tǒng)API文檔")
                        .version("1.0.0")
                        .description("這是一個基于SpringBoot 3.x的用戶管理系統(tǒng)API文檔，包含用戶CRUD、權(quán)限管理等接口")
                        // 聯(lián)系人信息
                        .contact(new Contact()
                                .name("技術(shù)部")
                                .email("tech@example.com")
                                .url("https://tech.example.com"))
                        // 許可證信息
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://www.apache.org/licenses/LICENSE-2.0")))
                // 可以添加全局參數(shù)、安全方案等
                ;
    }
}

這個配置類非常關(guān)鍵，它替代了 Swagger2 中的 Docket 配置。通過建造者模式，我們可以輕松配置文檔的標(biāo)題、版本、描述等基本信息。

第四步：配置文件優(yōu)化

在 application.yml 中添加一些實用配置：

# SpringDoc配置
springdoc:
  # API文檔接口是否啟用
  api-docs:
    enabled: true
    # 響應(yīng)格式支持json和yaml
    formats: [json, yaml]
  # 掃描的包路徑（指定你的控制器所在包）
  packages-to-scan: com.example.user.controller
  # 路徑匹配規(guī)則
  paths-to-match: /api/**, /admin/**
# Knife4j增強(qiáng)配置
knife4j:
  enable: true
  # 增強(qiáng)配置
  setting:
    # 自定義主頁
    enableHomeCustom: true
    # 主頁Markdown文件路徑
    homeCustomLocation: classpath:markdown/home.md
    # 是否顯示調(diào)試Tab
    enableDebug: true
    # 是否顯示搜索框
    enableSearch: true
    # 自定義Footer
    enableFooterCustom: true
    footerCustomContent: "? 2025 技術(shù)部 版權(quán)所有"

這些配置能讓你的文檔更符合團(tuán)隊需求。比如通過packages-to-scan指定掃描路徑可以提高啟動速度，homeCustomLocation可以自定義主頁內(nèi)容，非常適合放一些接口調(diào)用規(guī)范或 FAQ。

第五步：啟動驗證

一切就緒，啟動項目！訪問 Knife4j 的 UI 界面：http://localhost:8080/doc.html（注意不是 SwaggerUI 的舊路徑了）。

如果看到一個現(xiàn)代感十足的文檔界面，恭喜你集成成功！如果啟動失敗，先檢查控制臺報錯信息：

若出現(xiàn)NoSuchMethodError，大概率是 SpringDoc 版本與 SpringBoot 版本不匹配
若出現(xiàn)BeanDefinitionOverrideException，說明有舊的 Swagger 依賴沒清理干凈
若訪問 404，檢查是否配置了server.servlet.context-path，需要加上上下文路徑訪問

注解詳解：讓文檔更專業(yè)

好的文檔不僅能提高前后端協(xié)作效率，還能體現(xiàn)一個團(tuán)隊的專業(yè)素養(yǎng)。SpringDoc 采用了完全符合 OpenAPI 3 規(guī)范的注解體系，相比 Swagger2 更加簡潔明了。

核心注解對照表

對于從 Swagger2 遷移過來的同學(xué)，這張注解對照表必須收藏：

Swagger2 注解	SpringDoc (OpenAPI 3) 注解	說明
@Api	@Tag	描述控制器類
@ApiOperation	@Operation	描述接口方法
@ApiParam	@Parameter	描述請求參數(shù)
@ApiModel	@Schema	描述數(shù)據(jù)模型
@ApiModelProperty	@Schema	描述模型屬性
@ApiIgnore	@Parameter (hidden = true) 或 @Operation (hidden = true)	忽略某個元素

實戰(zhàn)注解示例

咱們通過一個用戶管理的控制器示例，看看這些注解如何使用：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/users")
// 控制器標(biāo)簽
@Tag(name = "用戶管理", description = "用戶CRUD、權(quán)限分配等接口")
public class UserController {
    // 接口描述
    @Operation(
            summary = "獲取用戶詳情",
            description = "根據(jù)用戶ID查詢用戶詳細(xì)信息，包含角色和權(quán)限",
            responses = {
                    @ApiResponse(responseCode = "200", description = "查詢成功",
                            content = @Content(schema = @Schema(implementation = UserDTO.class))),
                    @ApiResponse(responseCode = "404", description = "用戶不存在")
            }
    )
    @GetMapping("/{id}")
    public ResponseEntity<UserDTO> getUserById(
            // 路徑參數(shù)描述
            @Parameter(
                    name = "id",
                    description = "用戶ID",
                    required = true,
                    in = ParameterIn.PATH,
                    example = "1001"
            )
            @PathVariable Long id) {
        // 業(yè)務(wù)邏輯...
        return ResponseEntity.ok(new UserDTO());
    }
    @Operation(summary = "創(chuàng)建用戶", description = "新增用戶信息，用戶名不能重復(fù)")
    @PostMapping
    public ResponseEntity<UserDTO> createUser(
            @Parameter(description = "用戶信息", required = true)
            @RequestBody UserCreateDTO user) {
        // 業(yè)務(wù)邏輯...
        return ResponseEntity.ok(new UserDTO());
    }
}

數(shù)據(jù)模型的注解示例：

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import lombok.Data;
@Data
@Schema(description = "用戶創(chuàng)建請求DTO")
public class UserCreateDTO {
    @NotBlank(message = "用戶名不能為空")
    @Size(min = 3, max = 20, message = "用戶名長度必須在3-20之間")
    @Schema(description = "用戶名", example = "zhangsan", minLength = 3, maxLength = 20)
    private String username;
    @NotBlank(message = "密碼不能為空")
    @Size(min = 6, message = "密碼長度不能少于6位")
    @Schema(description = "密碼", example = "P@ssw0rd", minLength = 6, writeOnly = true)
    private String password;
    @Email(message = "郵箱格式不正確")
    @Schema(description = "郵箱地址", example = "zhangsan@example.com")
    private String email;
}

注意到?jīng)]？SpringDoc 的注解和 JSR303 的校驗注解可以完美共存，既保證了接口文檔的清晰，又實現(xiàn)了參數(shù)校驗，一舉兩得！這比 Swagger2 的注解體系要簡潔得多。

高級注解技巧

文件上傳接口：需要特別指定參數(shù)類型為multipart/form-data：

@Operation(summary = "上傳用戶頭像")
@PostMapping(value = "/avatar", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<String> uploadAvatar(
        @Parameter(description = "用戶ID", required = true)
        @RequestParam Long userId,
        @Parameter(description = "頭像文件", required = true, 
                  content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA_VALUE))
        @RequestPart MultipartFile file) {
    // 業(yè)務(wù)邏輯...
    return ResponseEntity.ok("上傳成功");
}

全局響應(yīng)頭：如果所有接口都返回某個響應(yīng)頭，可以在配置類中全局配置：

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(apiInfo())
            .components(new Components()
                    .addResponses("default", new ApiResponse()
                            .description("默認(rèn)響應(yīng)")
                            .headers(Map.of(
                                    "X-Request-ID", new Header()
                                            .description("請求唯一標(biāo)識")
                                            .schema(new Schema().type("string"))
                            ))
                    )
            );
}

Knife4j 增強(qiáng)功能：讓文檔更好用

如果說 SpringDoc 是 "內(nèi)功心法"，那 Knife4j 就是 "外功招式"—— 它在 SpringDoc 的基礎(chǔ)上增加了很多實用功能，讓 API 文檔不僅好看，更好用。

自定義主頁

通過前面配置的homeCustomLocation，我們可以用 Markdown 編寫自定義主頁。這對于團(tuán)隊協(xié)作非常有用，可以放接口規(guī)范、更新日志、常見問題等內(nèi)容：

# 用戶管理系統(tǒng)API文檔

歡迎使用用戶管理系統(tǒng)的API文檔中心！本文檔包含所有可用接口的詳細(xì)說明和調(diào)試功能。

## 接口規(guī)范

1. 所有接口基礎(chǔ)路徑：`/api`
2. 數(shù)據(jù)交換格式：JSON
3. 日期時間格式：yyyy-MM-dd HH:mm:ss
4. 認(rèn)證方式：Bearer Token

## 最近更新

- 2025-08-01：新增用戶批量導(dǎo)入接口
- 2025-07-15：用戶查詢接口增加分頁參數(shù)

## 常見問題

Q: 為什么調(diào)用接口返回401？
A: 請先調(diào)用登錄接口獲取Token，并在請求頭中添加Authorization: Bearer {token}

Q: 密碼有什么格式要求？
A: 密碼長度至少6位，包含大小寫字母和數(shù)字

這種自定義能力讓 API 文檔不再只是接口的堆砌，而是真正的團(tuán)隊協(xié)作手冊。

接口調(diào)試增強(qiáng)

Knife4j 在接口調(diào)試方面做了很多優(yōu)化：

動態(tài)參數(shù)調(diào)試：開啟enableDynamicParameter后，可以動態(tài)添加請求參數(shù)，對于測試非標(biāo)準(zhǔn)接口非常方便：

knife4j:
  setting:
    enableDynamicParameter: true

調(diào)試歷史記錄：自動記錄每次調(diào)試的參數(shù)和結(jié)果，支持一鍵重新調(diào)試，再也不用重復(fù)輸入?yún)?shù)了。多環(huán)境切換：可以預(yù)設(shè)開發(fā)、測試、生產(chǎn)等不同環(huán)境的基礎(chǔ) URL，一鍵切換調(diào)試環(huán)境，省去手動修改域名的麻煩。

離線文檔導(dǎo)出

雖然在線文檔方便調(diào)試，但很多時候我們需要離線文檔進(jìn)行歸檔或交付。Knife4j 支持導(dǎo)出多種格式的離線文檔：

Markdown 格式：適合放入項目知識庫
HTML 格式：保留在線文檔的樣式和交互
Word 格式：適合交付給非技術(shù)人員

導(dǎo)出方法也很簡單：在文檔界面右上角點擊 "下載" 按鈕，選擇對應(yīng)的格式即可。對于需要定期生成離線文檔的場景，還可以通過 Maven 插件實現(xiàn)自動化導(dǎo)出：

<plugin>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-maven-plugin</artifactId>
    <version>4.3.0</version>
    <configuration>
        <apiDocUrl>http://localhost:8080/v3/api-docs</apiDocUrl>
        <exportDir>./docs</exportDir>
        <exportType>markdown</exportType>
    </configuration>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>export</goal>
            </goals>
        </execution>
    </executions>
</plugin>

權(quán)限控制與安全

API 文檔雖然方便，但也可能泄露敏感信息。Knife4j 提供了多種安全控制手段：

生產(chǎn)環(huán)境開關(guān)：通過配置控制生產(chǎn)環(huán)境是否啟用文檔：

knife4j:
  enable: ${knife4j.enable:true} # 可以通過環(huán)境變量控制

在生產(chǎn)環(huán)境部署時，設(shè)置knife4j.enable=false即可關(guān)閉文檔功能。接口權(quán)限控制：結(jié)合 Spring Security，可以實現(xiàn)文檔的訪問權(quán)限控制：

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                // 允許所有人訪問文檔
                .requestMatchers("/doc.html", "/webjars/**", "/v3/api-docs/**").permitAll()
                // 其他接口需要認(rèn)證
                .anyRequest().authenticated()
        );
        return http.build();
    }
}

接口隱藏：通過@Operation(hidden = true)可以隱藏內(nèi)部接口，避免對外暴露敏感接口。

高級玩法：讓文檔成為協(xié)作利器

API 文檔不應(yīng)該只是開發(fā)完成后的 "副產(chǎn)品"，而應(yīng)該成為貫穿整個開發(fā)流程的協(xié)作工具。結(jié)合 SpringDoc 和 Knife4j 的高級特性，我們可以打造更高效的團(tuán)隊協(xié)作流程。

接口分組與版本管理

對于大型項目，所有接口擠在一起會顯得雜亂無章。我們可以按業(yè)務(wù)模塊或版本對接口進(jìn)行分組：

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(apiInfo())
            .addTagsItem(new Tag().name("用戶管理").description("V1版本用戶接口"))
            .addTagsItem(new Tag().name("用戶管理V2").description("V2版本用戶接口"));
}

// 在控制器上指定分組
@Tag(name = "用戶管理V2")
@RestController
@RequestMapping("/api/v2/users")
public class UserV2Controller { ... }

在 Knife4j 界面中，就可以通過標(biāo)簽切換不同模塊的接口，非常方便。對于版本迭代頻繁的項目，這種分組能力尤為重要。

與測試工具集成

好的 API 文檔應(yīng)該能無縫對接測試流程。SpringDoc 生成的 OpenAPI 規(guī)范文檔可以直接導(dǎo)入多種測試工具：

Postman：通過 "Import -> Link" 導(dǎo)入http://localhost:8080/v3/api-docs，自動生成接口集合
JMeter：結(jié)合 OpenAPI 插件，可以基于文檔生成測試用例
自動化測試：通過 OpenAPI Generator 生成接口測試代碼

例如用 OpenAPI Generator 生成 Java 測試客戶端：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.3.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>http://localhost:8080/v3/api-docs</inputSpec>
                <generatorName>java</generatorName>
                <configOptions>
                    <sourceFolder>src/test/java</sourceFolder>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

這種集成能力讓 API 文檔從 "被動查閱" 變成 "主動驅(qū)動" 測試流程的核心。

CI/CD 流程集成

在持續(xù)集成流程中，我們可以自動檢查接口文檔的完整性，確保代碼和文檔同步更新：

添加文檔完整性檢查插件
在 CI pipeline 中配置文檔生成步驟
將生成的文檔部署到內(nèi)部文檔中心

例如在 GitLab CI 中配置：

stages:
  - build
  - docs

build:
stage: build
script:
    - mvn clean package

generate-docs:
stage: docs
script:
    - mvn springdoc:generate
    - mvn knife4j:export
artifacts:
    paths:
      - ./docs
only:
    - main

通過這種方式，每次代碼合并到主分支都會自動更新文檔，避免了 "代碼已更新，文檔未同步" 的尷尬局面。

避坑指南：常見問題與解決方案

雖然 SpringDoc + Knife4j 的組合已經(jīng)非常成熟，但在實際使用中還是可能遇到一些問題。這里總結(jié)了幾個高頻問題及解決方案：

版本沖突問題

最常見的問題就是版本不兼容，尤其是 SpringBoot 3.3.x 之后：

Caused by: java.lang.NoSuchMethodError: 
org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()Ljava/util/List;

解決方案：嚴(yán)格按照前面的版本對照表選擇依賴，SpringBoot 3.3.x 及以上需要使用 SpringDoc 2.6.x（可能需要 SNAPSHOT 版本）：

<repositories>
    <repository>
        <id>sonatype-snapshots</id>
        <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.6.0-SNAPSHOT</version>
    </dependency>
</dependencies>

接口掃描不完整

有時候會發(fā)現(xiàn)某些接口沒有出現(xiàn)在文檔中，可能的原因：

控制器不在packages-to-scan配置的包路徑下
方法沒有使用@GetMapping等請求注解
類或方法被@Hidden注解標(biāo)記了
請求路徑包含特殊字符，導(dǎo)致掃描失敗

解決方案：檢查包路徑配置，確保所有控制器都能被掃描到：

springdoc:
  packages-to-scan: com.example.controller, com.example.api # 多個包用逗號分隔
  paths-to-match: /** # 匹配所有路徑

靜態(tài)資源沖突

如果項目中自定義了靜態(tài)資源配置，可能會導(dǎo)致 Knife4j 的 UI 資源無法訪問，表現(xiàn)為訪問/doc.html時頁面空白。

解決方案：在 WebMvc 配置中放行 Knife4j 的靜態(tài)資源：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 放行Knife4j的靜態(tài)資源
        registry.addResourceHandler("/doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

注解不生效

有時候添加了注解但文檔中沒有生效，可能是因為：

使用了錯誤的注解（混用了 Swagger2 和 SpringDoc 的注解）
注解的屬性使用錯誤（比如@Schema的example寫成了examples）
沒有啟用注解處理器

解決方案：檢查注解包路徑，確保使用的是 OpenAPI 3 的注解：

// 正確的包路徑
import io.swagger.v3.oas.annotations.*;
// 錯誤的包路徑（Swagger2）
import io.swagger.annotations.*;

總結(jié)：為什么選擇 SpringDoc + Knife4j

寫到這里，相信大家對這套 API 文檔解決方案已經(jīng)有了全面的了解。最后咱們再來總結(jié)一下為什么它值得你放棄 SwaggerUI：

規(guī)范領(lǐng)先：完全支持 OpenAPI 3.0 規(guī)范，相比 Swagger 2.0 更完善、更靈活。
生態(tài)契合：專為 SpringBoot 設(shè)計，從 2.x 到 3.x 都有良好支持，避免了版本兼容問題。
注解簡潔：減少了專屬注解數(shù)量，與 JSR303 校驗注解兼容，降低代碼侵入性。
UI 體驗佳：Knife4j 提供的現(xiàn)代 UI 比 SwaggerUI 美觀得多，操作也更流暢。
功能豐富：離線文檔、接口分組、環(huán)境切換等實用功能一應(yīng)俱全。
持續(xù)更新：社區(qū)活躍度高，問題修復(fù)及時，不用擔(dān)心項目停更的風(fēng)險。
易于遷移：提供了清晰的注解映射關(guān)系，舊項目遷移成本低。

最重要的是，這套組合真正做到了 "開箱即用"—— 簡單配置就能得到專業(yè)級的 API 文檔，讓你把精力放在業(yè)務(wù)開發(fā)上，而不是和文檔工具較勁。

責(zé)任編輯：武曉燕來源：石杉的架構(gòu)筆記