告别Swagger UI！一款更适合 SpringBoot 的API文档新选择

Java精选面试题（微信小程序）：5000+道面试题和选择题，包含Java基础、并发、JVM、线程、MQ系列、Redis、Spring系列、Elasticsearch、Docker、K8s、Flink、Spark、架构设计、大厂真题等，在线随时刷题！

SpringDoc是什么

SpringDoc 是一个专为 Spring Boot 应用设计的库，能够自动生成符合 OpenAPI 3 规范的 API 文档。它通过扫描项目中的控制器、方法注解及配置，动态生成 JSON/YAML/HTML 格式的文档，并提供交互式界面（如 Swagger UI）供开发者查看和测试 API

与Swagger的关系

Swagger 作为 OpenAPI 规范的前身，贡献了 API 设计理念并推动了 OpenAPI 的标准化。其核心工具 Swagger UI 用于展示交互式文档。

SpringDoc 并非 Swagger 的替代品，而是基于 OpenAPI 3 规范的实现工具，并天然集成 Swagger UI 作为文档展示界面

为什么要选择SpringDoc

在SpringDoc面世之前，Spring生态中集成实现Swagger的技术为SpringFox，SpringFox与Swagger之间的协作关系如下

SpringFox

• • 代码扫描：SpringFox 在运行时扫描 Spring MVC 控制器（如@RestController）、方法注解（如@RequestMapping）以及 Swagger 专用注解（如@ApiOperation），提取接口的路径、参数、响应等信息

• • 生成 OpenAPI 规范文档： 将扫描结果转换为符合 Swagger 2.0 或 OpenAPI 3.0 规范的 JSON 文件

• • 集成 Spring 生态，提供 Docket 配置类，支持自定义接口扫描范围（如包路径、URL 匹配规则）和文档信息（如标题、版本、作者）

• • 可视化文档渲染：将 SpringFox 生成的 JSON 文件解析为交互式网页，通过浏览器访问（如http://localhost:8080/swagger-ui.html）

• • 提供接口列表、参数说明、请求示例，并支持在线测试 API（可直接发送请求并查看响应）

• • 标准化规范支持：Swagger 定义 OpenAPI 规范（原 Swagger 规范），为 API 描述提供统一标准（如接口路径、请求方法、数据类型），SpringFox 生成的 JSON 文件完全遵循此规范，确保与其他 Swagger 工具（如Swagger Editor）兼容

• • 开发阶段：开发者在 Spring 控制器中添加 Swagger 注解（如@Api、@ApiParam），描述接口细节

• • 运行时：SpringFox 扫描代码并生成 JSON 文档

• • 展示阶段：Swagger UI 读取 JSON 文件，渲染为可视化界面供团队使用

在2020时，由于SpringFox官方基本停止维护，不再发布新版本或修复问题，再加上他无法适配 Spring Boot 2.6+ 及 3.x 版本，导致与新版本 Spring 生态冲突（如路径匹配失效、注解不兼容）。以及配置的复杂性导致他逐渐退出市场

转而由更新的技术–SpringDoc接过接力棒，SpringDoc完美支持 Spring Boot 2.6+ 及 3.x（含 JDK 17+），并且原生支持OpenAPI 3 规范，除此之外，如果不需要特殊的复杂配置，甚至可以零配置，仅需引入一个依赖，即可实现开箱即用，还有他直接使用 JSR-303 规范注解（如@Schema、@Parameter），替代 SpringFox 的专属注解（如@ApiModel），降低了开发人员的学习成本

正式发布

最小化配置使用

不多说废话了，下面我们正式开始，首先我们先介绍最简单，最小化的引入以及使用方式

第一步：引入Jar包

     

 org.springdoc groupId>     

 springdoc-openapi-starter-webmvc-ui artifactId>     

 2.5.0 version>  dependency>

第二步：配置配置文件

正常使用SpringDoc，或多或少都会进行一些配置文件的配置，但是由于这里是进行最小化配置，所以这里不进行配置文件配置，仅仅介绍几个重要配置的默认项，给大家一个基础印象，方便大家理解后面运行时为什么要这样做，当然，如果不感兴趣的小伙伴也可以直接跳过，跟着步骤走，并不影响使用

# application.yml springdoc: # SpringDoc的API包扫描路径，如果不配置，SpringDoc 自动扫描整个项目类路径，它会自动识别所有 @RestController、@RequestMapping 等注解，生成 API 文档 packages-to-scan:com.example.controller swagger-ui:     # 是否开启swagger界面，依赖OpenApi，默认为true，如果要开启需要OpenApi同时开启     enabled:true     # 内置 Swagger UI 的访问路径，默认值为/swagger-ui/index.html     path:/swagger-ui/index.html     # 指定OpenAPI文档的URL（注意这里一定要与api-docs.path保持一致，否则会请求失败）     url:/v3/api-docs     # 是否禁用Swagger UI自带的示例接口（如 Petstore 等默认接口），默认值为false，仅展示当前项目的 API     disable-swagger-default-url:false api-docs:     # 是否启用OpenAPI文档端点，默认为true     enabled:true     # OpenAPI 3规范的文档访问路径，默认值为/v3/api-docs     path: /api-docs

第三步：添加一个配置类，用于设置Swagger-UI页面的一些基础信息的展示

@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 "请求成功";     } }

添加注解

@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 "请求成功";     } }

至此为止，SpringDoc的最小化使用已经全部完成（请注意，以上所有配置生效的前提是，当前Spring项目未添加任何过滤器、拦截器，以及未使用SpringSecurity等安全框架，否则，仅仅进行最小化配置是无法运行的，因为一些默认配置可能会被拦截，如果需要更复杂配置，请继续往下看）

SpringDoc中简单分组配置（包含编程式配置与声明式配置）

上方仅仅只是展示了SpringDoc的最基础用法，接下来，我们展示SpringDoc的一种常用用法：分组，先上效果图，让大家了解是个什么功能

接下来开始进行详细配置：

方式一：编程式配置（灵活性高、扩展性强、调试友好）

@Configuration @OpenAPIDefinition(info = @Info(         title = "项目API文档",         version = "1.0",         description = "SpringBoot项目接口文档" )) publicclassSpringDocConfig {     /**      * 商品分组的配置（使用请求路径扫描的方式进行配置）      * @return org.springdoc.core.models.GroupedOpenApi      * @author ren      * @date 2025/07/06 17:17      */     @Bean     public GroupedOpenApi userGroup() {         // 使用路径匹配方式：仅包含 /api/product/** 下的接口         return GroupedOpenApi.builder()                 .group("商品模块")                 .pathsToMatch("/api/product/**")   // 路径匹配                 .build();     }     /**      * 会员分组的配置（使用包扫描的方式进行配置）      * @return org.springdoc.core.models.GroupedOpenApi      * @author ren      * @date 2025/07/06 17:17      */     @Bean     public GroupedOpenApi productGroup() {         // 使用包扫描方式：扫描 com.ren.main.controller.member 包下的所有接口         return GroupedOpenApi.builder()                 .group("用户模块")                 .packagesToScan("com.ren.main.controller.member") // 包扫描                 .build();     } }

这种配置方式的原理是通过添加GroupedOpenApi类型的Bean，项目启动时，SpringDoc会寻找环境中是否存在GroupedOpenApi类型的Bean，如果存在，则会创建分组进行展示

注意：

• • 一旦这里配置了分组方式展示，那么在application.yml配置文件中配置的springdoc.packages-to-scan就会失效，因为SpringDoc的扫描机制，分组配置的扫描路径优先级大于配置文件配置的扫描优先级

• • 路径扫描有两种方式，一种是根据请求路径进行扫描，一种是根据包路径进行扫描，上方都有进行配置

• • 如果多个分组中有重合的路径，也就是说一个接口在多个分组配置的路径中都能扫描到，那么这个接口会存在于多个分组中

以下展示我的代码结构，方便大家理解：

大家会发现，我的目录中有一个MainController的内容，在页面中没有展示了，这是为什么呢？原因我上面提过了，因为分组的配置会覆盖默认配置与配置文件配置，而分组配置中由于没有包含MainController的内容，所以，MainController的内容没有地方展示了

那么如果想要展示出这个文件中的接口该怎么办呢？很简单，在分组中再加一个默认分组，用于展示所有接口内容即可，如下

@Configuration @OpenAPIDefinition(info = @Info(         title = "项目API文档",         version = "1.0",         description = "SpringBoot项目接口文档" )) publicclassSpringDocConfig {     /**      * 默认分组      * @return org.springdoc.core.models.GroupedOpenApi      * @author ren      * @date 2025/07/06 17:38      */     @Bean     public GroupedOpenApi defaultGroup() {         return GroupedOpenApi.builder()                 .group("默认分组")                 .pathsToMatch("/**")   // 路径匹配                 .build();     }     /**      * 商品分组的配置（使用请求路径扫描的方式进行配置）      * @return org.springdoc.core.models.GroupedOpenApi      * @author ren      * @date 2025/07/06 17:17      */     @Bean     public GroupedOpenApi userGroup() {         // 使用路径匹配方式：仅包含 /api/product/** 下的接口         return GroupedOpenApi.builder()                 .group("商品模块")                 .pathsToMatch("/api/product/**")   // 路径匹配                 .build();     }     /**      * 会员分组的配置（使用包扫描的方式进行配置）      * @return org.springdoc.core.models.GroupedOpenApi      * @author ren      * @date 2025/07/06 17:17      */     @Bean     public GroupedOpenApi productGroup() {         // 使用包扫描方式：扫描 com.ren.main.controller.member 包下的所有接口         return GroupedOpenApi.builder()                 .group("用户模块")                 .packagesToScan("com.ren.main.controller.member") // 包扫描                 .build();     } }

配置后展示的内容

看上面的图，MainController的内容展示在这里了，同时ProductController和MemberController的内容也展示在这里了，这是为什么呢，原因我上面说过了，如果一个请求被多个分组扫描到，那么他会展示在多个分组中

方式二：声明式配置（配置集中管理、可使用多配置文件进行环境隔离）

springdoc:   group-configs:     -group:'默认分组'       paths-to-match:'/**'     -group:'商品模块'       paths-to-match:'/api/product/**'     -group:'用户模块'       packages-to-scan: 'com.ren.main.controller.member'

如上：效果与方式一相同

如果项目中重写了WebMvcConfigurer的addResourceHandlers方法，所需进行的处理

WebMvcConfigurer

WebMvcConfigurer是 Spring MVC 的配置中枢，用于定制化 Spring MVC 的各种行为。它不是过滤器或拦截器，而是一个配置接口（类似汽车的仪表盘），让你调整 Spring MVC 的运行方式。

他所拥有的方法

• •addInterceptors(registry)：注册拦截器

• •addCorsMappings(registry)：配置跨域权限

• •addResourceHandlers(registry)：指定静态资源路径

• •addViewControllers(registry)：设置简易页面跳转

• •configureMessageConverters(list)：定制JSON/XML解析器

• •configurePathMatch(configurer)：调整URL匹配规则

• •addArgumentResolvers(list)：自定义请求参数处理器

• •addReturnValueHandlers(list)：自定义返回值处理器

• •configureContentNegotiation(configurer)：内容协商配置（响应格式协商）

如果我们重写了WebMvcConfigurer的addResourceHandlers方法，那么原本Spring自己默认配置的所有的静态资源的指向路径就全都会失效，于是就需要我们自己去配置指定

@Configuration publicclassResourcesConfigimplementsWebMvcConfigurer {     @Override     publicvoidaddResourceHandlers(ResourceHandlerRegistry registry) {         registry.addResourceHandler("/swagger-ui/**")             .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/")             .setCacheControl(CacheControl.maxAge(5, TimeUnit.HOURS).cachePublic());     } }

按照如上设置后，SpringDoc将恢复正常（注意新版的SpringDoc和老版的SpringFox配置有所区别，这里只展示新版SpringDoc的配置方法）如果大家对老版配置有需要，可以留言，留言人多会单独出一期

如果项目引入了SpringSecurity需要进行的处理

由于项目引入了SpringSecurity，导致如果项目不经过认证无法访问系统资源，我们就需要在SpringSecurity的配置文件中放开SpringDoc相关的静态资源的拦截，如下

@Configuration @EnableWebSecurity @EnableMethodSecurity publicclassSecurityConfig {     /*      * 配置过滤器链      * @param http      * @return org.springframework.security.web.SecurityFilterChain      * @author ren      * @date 2025/04/17 21:30      */     @Bean     public SecurityFilterChain securityFilterChain(HttpSecurity http)throws Exception {         http.authorizeHttpRequests(auth -> auth                 // 允许 OPTIONS 方法通过                 .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()                 // 静态资源，可匿名访问                 .requestMatchers(request -> {                     Stringpath= 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/**", "/druid/**")                 .permitAll()                 // 除上面外的所有请求全部需要鉴权认证                 .anyRequest().authenticated()         );         return http.build();     } }

添加如上配置后，即可放开SpringSecurity的认证限制

总结

以上就是今天要讲的内容，本文简单介绍了SpringDoc整合在SpringBoot项目中的步骤，如果有遗漏，请大家留言，看到后会进行补充。

作者：犯困嫌疑人(づ ●─● )づ

https://blog.csdn.net/2503_92695612

公众号“Java精选”所发表内容注明来源的，版权归原出处所有（无法查证版权的或者未注明出处的均来自网络，系转载，转载的目的在于传递更多信息，版权属于原作者。如有侵权，请联系，笔者会第一时间删除处理！

最近有很多人问，有没有读者交流群！加入方式很简单，公众号Java精选，回复“加群”，即可入群！

文章有帮助的话，点在看，转发吧！