甩掉 Swagger UI！SpringBoot API 文檔神器強勢登場

作者：編程疏影 2025-08-14 07:40:05

過去的 Swagger + SpringFox 方案，在新版本 Spring Boot 中已經力不從心；而 SpringDoc 作為 OpenAPI 3 的原生實現，不僅穩定高效，還能通過最小化配置快速上手，滿足中大型項目的 API 文檔管理需求。

在現代后端開發中，API 文檔已經成為項目協作的基石——它不僅幫助前后端快速對接，也能為運維、測試提供可靠的接口依據。過去，我們在 Spring Boot 項目中常用 Swagger + SpringFox 來生成交互式文檔，但隨著 Spring 版本的升級，這一套組合逐漸顯露疲態：維護停滯、版本不兼容、配置繁瑣…… 如果你還在為升級 Spring Boot 后 Swagger 失效而抓狂，那么今天介紹的 SpringDoc，將是你值得關注的下一代方案——它能在 Spring Boot 3.x + JDK17 環境下穩定運行，原生支持 OpenAPI 3 規范，并且實現了“零配置開箱即用”。

SpringDoc 是什么

SpringDoc 是一款專為 Spring Boot 應用打造的 API 文檔生成工具，它會自動掃描項目中的：

控制器類（@RestController）
請求映射（@RequestMapping、@GetMapping 等）
OpenAPI 3 注解（@Schema、@Parameter 等）

然后動態生成 JSON / YAML / HTML 格式的 API 規范文件，并集成交互式的 Swagger UI 頁面，讓開發者直接在瀏覽器中調試接口。

核心能力：

自動掃描項目 API，無需手寫文檔
支持最新 OpenAPI 3 規范
集成 Swagger UI，可直接在線調試
與 Spring Boot 3.x 完美兼容

它與 Swagger 的關系

要理解 SpringDoc 的優勢，我們先簡單回顧 Swagger 的角色。

Swagger 是 OpenAPI 規范的前身，負責推動 API 描述標準化
Swagger UI 是它的可視化工具，用于渲染交互式文檔
SpringFox 曾是 Spring 生態中連接 Swagger 的橋梁，負責掃描代碼并生成 JSON 格式的 OpenAPI 文檔

在 2020 年以后，SpringFox 停止更新，并且在 Spring Boot 2.6+ / 3.x 中出現大量不兼容問題，比如：

路徑匹配失效
注解沖突
配置異常復雜

于是，SpringDoc 成為了替代者：它直接基于 OpenAPI 3 實現，無需依賴 SpringFox，并且保留了 Swagger UI 的可視化體驗。

為什么選擇 SpringDoc

選擇 SpringDoc 的理由非常直接：

官方持續維護：兼容 Spring Boot 最新版本
配置簡單：引入依賴即可運行
原生 OpenAPI 3 支持：使用 JSR-303 注解替代 Swagger 專用注解
零侵入性：不破壞原有代碼結構
性能穩定：加載速度快，資源占用低

最小化集成步驟

引入依賴

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

可選配置（application.yml）

springdoc:
  packages-to-scan: com.icoderoad.controller
  swagger-ui:
    enabled: true
    path: /swagger-ui/index.html
    url: /v3/api-docs
    disable-swagger-default-url: false
  api-docs:
    enabled: true
    path: /api-docs

如果不配置，SpringDoc 會自動掃描全項目的 Controller 類。

基礎信息配置類

package com.icoderoad.config;


import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Configuration;


@Configuration
@OpenAPIDefinition(
    info = @Info(title = "項目 API 文檔", version = "1.0", description = "SpringBoot 項目接口文檔")
)
public class SpringDocConfig {
}

添加注解展示 API 信息

package com.icoderoad.controller;


import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;


@RestController
@RequestMapping("/main")
@Tag(name = "演示Controller", description = "演示接口")
public class MainController {


    @GetMapping("/index")
    @Operation(summary = "演示方法", description = "接口功能說明")
    public String index(@Parameter(description = "參數1", required = true) String str1) {
        return "請求成功";
    }
}

訪問地址：

http://localhost:8080/swagger-ui/index.html

分組配置

編程式分組

package com.icoderoad.config;


import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;


@Configuration
public class SpringDocGroupConfig {


    @Bean
    public GroupedOpenApi defaultGroup() {
        return GroupedOpenApi.builder().group("默認分組").pathsToMatch("/**").build();
    }


    @Bean
    public GroupedOpenApi productGroup() {
        return GroupedOpenApi.builder().group("商品模塊").pathsToMatch("/api/product/**").build();
    }


    @Bean
    public GroupedOpenApi userGroup() {
        return GroupedOpenApi.builder().group("用戶模塊").packagesToScan("com.icoderoad.controller.member").build();
    }
}

聲明式分組（application.yml）

springdoc:
  group-configs:
    - group: 默認分組
      paths-to-match: "/**"
    - group: 商品模塊
      paths-to-match: "/api/product/**"
    - group: 用戶模塊
      packages-to-scan: "com.icoderoad.controller.member"

特殊場景處理

WebMvcConfigurer 重寫資源映射

package com.icoderoad.config;


import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.*;


import java.util.concurrent.TimeUnit;


@Configuration
public class ResourcesConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/")
                .setCacheControl(org.springframework.http.CacheControl.maxAge(5, TimeUnit.HOURS).cachePublic());
    }
}

Spring Security 放行配置

package com.icoderoad.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.*;


@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {


    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
                .requestMatchers("/swagger-ui/**", "/*/api-docs/**", "/swagger-resources/**", "/webjars/**").permitAll()
                .anyRequest().authenticated()
        );
        return http.build();
    }
}

總結

過去的 Swagger + SpringFox 方案，在新版本 Spring Boot 中已經力不從心；而 SpringDoc 作為 OpenAPI 3 的原生實現，不僅穩定高效，還能通過最小化配置快速上手，滿足中大型項目的 API 文檔管理需求。如果你想在 Spring Boot 3.x + JDK17+ 環境下擁有一個即插即用、可擴展的 API 文檔工具，那么 SpringDoc 將是你不容錯過的選擇。它讓文檔與代碼同步更新，讓前后端協作更加流暢，讓 API 開發更具現代感。

責任編輯：武曉燕來源：路條編程