甩掉 Swagger UI！SpringBoot API 文档神器强势登场

最新推荐文章于 2025-10-15 16:04:17 发布

原创最新推荐文章于 2025-10-15 16:04:17 发布 · 624 阅读

CC 4.0 BY-SA版权

文章标签：

过去的 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 开发更具现代感。