SpringDoc：Spring Boot 应用 API 文档生成的现代化解决方案
概述
SpringDoc 是一个专为 Spring Boot 应用设计的开源库，能够自动生成符合 OpenAPI 3 规范的 API 文档。它通过扫描项目中的控制器、方法注解及相关配置，动态生成 JSON/YAML/HTML 格式的文档，并提供 Swagger UI 等交互式界面供开发者查看和测试 API。
与 Swagger 的关系
Swagger 作为 OpenAPI 规范的前身，贡献了 API 设计理念并推动了 OpenAPI 的标准化进程，其核心工具 Swagger UI 用于展示交互式文档。需要明确的是：
- SpringDoc 不是 Swagger 的替代品，而是基于 OpenAPI 3 规范的实现工具
- SpringDoc 天然集成 Swagger UI 作为文档展示界面
- 它使用现代 JSR-303 规范注解，替代了传统 Swagger 专属注解
为什么选择 SpringDoc
SpringFox 的衰落
在 SpringDoc 面世之前，Spring 生态中主要使用 SpringFox 实现 Swagger 集成：
SpringFox 工作机制：
- 运行时扫描 Spring MVC 控制器（如
@RestController）、方法注解（如@RequestMapping）及 Swagger 专用注解 - 提取接口的路径、参数、响应等信息
- 生成符合 Swagger 2.0 或 OpenAPI 3.0 规范的 JSON 文件
- 集成 Spring 生态，提供 Docket 配置类支持自定义配置
Swagger UI 作用：
- 将 SpringFox 生成的 JSON 文件解析为交互式网页
- 提供接口列表、参数说明、请求示例和在线测试功能
- 确保与其他 Swagger 工具兼容
协作流程：
- 开发阶段：开发者在控制器中添加 Swagger 注解描述接口细节
- 运行时：SpringFox 扫描代码并生成 JSON 文档
- 展示阶段：Swagger UI 读取 JSON 文件并渲染可视化界面
SpringDoc 的优势
自 2020 年起，SpringFox 官方基本停止维护，导致：
- 无法适配 Spring Boot 2.6+ 及 3.x 版本
- 与新版本 Spring 生态冲突（路径匹配失效、注解不兼容）
- 配置复杂性问题
SpringDoc 作为新一代解决方案具有以下优势：
- 完美支持 Spring Boot 2.6+ 及 3.x（含 JDK 17+）
- 原生支持 OpenAPI 3 规范
- 零配置开箱即用（仅需引入一个依赖）
- 使用 JSR-303 规范注解（如
@Schema、@Parameter），降低学习成本
最小化配置使用
第一步：引入依赖
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version><!-- 建议使用最新版本 -->
</dependency>
第二步：配置文件说明（可选）
# application.yml
springdoc:# API 包扫描路径（不配置则自动扫描整个项目）packages-to-scan: com.example.controllerswagger-ui:enabled: true # 是否开启 Swagger 界面path: /swagger-ui/index.html # 访问路径url: /v3/api-docs # 指定 OpenAPI 文档 URLdisable-swagger-default-url: false # 是否禁用自带示例接口api-docs:enabled: true # 启用 OpenAPI 文档端点path: /api-docs # 文档访问路径
第三步：基础配置类
@Configuration
@OpenAPIDefinition(info = @Info(title = "项目API文档",version = "1.0",description = "SpringBoot项目接口文档"
))
public class SpringDocConfig {// 无需额外配置，注解已定义基本信息
}
完成以上步骤后，访问 http://localhost:8080/swagger-ui/index.html 即可查看界面（无 Controller 时显示空页面）。
第四步：添加接口注解
未加注解的 Controller：
@RestController
@RequestMapping("/main")
public class MainController {@GetMapping("/index")public String index(String str1) {return "请求成功";}
}
界面显示效果：仅显示基础路径和参数信息，缺少详细描述。
添加注解的 Controller：
@RestController
@RequestMapping("/main")
@Tag(name = "演示controller", description = "演示controller")
public class MainController {@GetMapping("/index")@Operation(summary = "演示方法", description = "演示方法的注释")public String index(@Parameter(description = "参数1", required = true) String str1) {return "请求成功";}
}
界面显示效果：包含完整的模块描述、方法说明和参数说明。
注意：以上配置生效前提是项目未添加过滤器、拦截器或 Spring Security 等安全框架，否则需要额外配置。
分组配置
SpringDoc 支持灵活的 API 分组展示功能。
编程式配置（推荐）
@Configuration
@OpenAPIDefinition(info = @Info(title = "项目API文档",version = "1.0",description = "SpringBoot项目接口文档"
))
public class SpringDocConfig {// 默认分组（包含所有接口）@Beanpublic GroupedOpenApi defaultGroup() {return GroupedOpenApi.builder().group("默认分组").pathsToMatch("/**").build();}// 商品模块分组（路径匹配方式）@Beanpublic GroupedOpenApi productGroup() {return GroupedOpenApi.builder().group("商品模块").pathsToMatch("/api/product/**").build();}// 用户模块分组（包扫描方式）@Beanpublic GroupedOpenApi userGroup() {return GroupedOpenApi.builder().group("用户模块").packagesToScan("com.example.controller.user").build();}
}
声明式配置
springdoc:group-configs:- group: '默认分组'paths-to-match: '/**'- group: '商品模块'paths-to-match: '/api/product/**'- group: '用户模块'packages-to-scan: 'com.example.controller.user'
注意事项
- 分组配置优先级高于配置文件中的
packages-to-scan配置 - 支持路径匹配和包扫描两种方式
- 同一接口可同时存在于多个分组中
- 如不配置默认分组，未匹配的接口将不会显示
常见问题处理
重写 WebMvcConfigurer 时的处理
如果项目重写了 addResourceHandlers 方法，需要手动添加 SpringDoc 资源映射：
@Configuration
public class ResourcesConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/").setCacheControl(CacheControl.maxAge(5, TimeUnit.HOURS).cachePublic());}
}
集成 Spring Security 时的处理
需要在 Security 配置中放开相关资源的访问权限：
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {@Beanpublic SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {http.authorizeHttpRequests(auth -> auth.requestMatchers(HttpMethod.OPTIONS, "/**").permitAll().requestMatchers(request -> {String path = request.getServletPath();return (request.getMethod().equals("GET") && ("/".equals(path) || path.endsWith(".html") || path.endsWith(".css") || path.endsWith(".js")));}).permitAll().requestMatchers("/swagger-ui/**", "/*/api-docs/**", "/swagger-resources/**", "/webjars/**").permitAll().anyRequest().authenticated());return http.build();}
}
我的项目结构：可参考
总结
SpringDoc 为 Spring Boot 应用提供了现代化、标准化的 API 文档生成方案。相比传统的 SpringFox，它具有更好的兼容性、更简单的配置方式和更低的维护成本。通过本文介绍的配置方法和最佳实践，开发者可以快速集成并定制符合项目需求的 API 文档系统。
关键优势总结：
- 开箱即用：最小配置即可快速上手
- 全面兼容：支持最新 Spring Boot 和 JDK 版本
- 灵活分组：支持多种方式的 API 分类管理
- 生态集成：无缝对接 Spring Security 等常用组件
- 规范标准：基于 OpenAPI 3 和 JSR-303 标准
通过合理运用 SpringDoc，团队可以显著提升 API 开发效率和文档质量，促进前后端协作的顺畅进行。
)
)
