当前位置：首页 > news >正文

一款更适合 SpringBoot 的API文档新选择（Spring Boot 应用 API 文档）

news 2025/8/22 7:17:49

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();}
}