1. 先搞清楚：SpringDoc和Swagger到底是什么关系
这两年经常有朋友问我，Swagger和SpringDoc到底选哪个，网上教程一堆但版本五花八门，照着配还总报错。这个问题的根源在于很多人没意识到，Swagger这个品牌在Java生态里其实经历了两次大的代际更替。
Swagger 2时代，Springfox是绝对的主流。那时候大家都在用springfox-swagger2配合springfox-swagger-ui，通过@EnableSwagger2注解开启，访问/swagger-ui.html查看文档页面。但Springfox的问题也很明显：它和Spring MVC的耦合很重，对Spring Boot 2.6之后PathPatternMatcher的变更兼容得很慢，更别说Spring Boot 3.0直接改成Jakarta EE规范后，Springfox基本就断了更新。
OpenAPI 3时代，就得靠SpringDoc了。SpringDoc一开始就瞄准了OpenAPI 3规范，是springdoc-openapi这个项目在维护。它最大的优势在于自动装配做得极致，你只要引入依赖，什么都不用配，启动项目后访问/swagger-ui.html就能看到文档页面，对应的JSON接口是/v3/api-docs。而且SpringDoc从设计上就考虑了Spring Boot 2.x和3.x的差异，springdoc-openapi-starter-webmvc-ui对应Spring Boot 3，springdoc-openapi-ui对应Spring Boot 2，不会出现版本不对导致项目起不来的情况。
我个人的建议非常明确：新项目一律用SpringDoc，老项目只要是Spring Boot 2.6以上的也尽量迁过来。Springfox的坑我已经踩够了——接口多了以后文档生成特别慢，偶尔还会把泛型解析成乱七八糟的结构，更重要的是它已经停止维护，你没法指望一个没人维护的库去适配未来的Spring版本。
打个比方，Springfox像是一台只认老式加油枪的车，加油站升级了油枪规格，这车就加不了油了。SpringDoc则是直接按新国标设计的车，加油站再怎么升级它都能适应。
2. SpringBoot 3项目里SpringDoc的落地配置与常用注解
2.1 依赖引入和自动配置的验证
Spring Boot 3项目里用SpringDoc，只需要一个核心依赖：
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.6.0</version> </dependency>注意这个依赖的groupId是org.springdoc，不是io.springfox，很多从Springfox迁移过来的人容易在这写错。如果你用的是Spring Boot 2.x，对应的依赖是org.springdoc:springdoc-openapi-ui。
引入依赖后启动项目，直接在浏览器访问http://localhost:8080/swagger-ui.html，如果能看到Swagger UI页面，说明自动配置已经生效了。同时可以访问http://localhost:8080/v3/api-docs验证OpenAPI的JSON结构是否正常返回。这一步不需要写任何配置类。
2.2 核心注解的实用写法
SpringDoc完全兼容OpenAPI 3的注解，最常用的几个场景我直接给你示范。
接口描述：
@Operation(summary = "查询用户列表", description = "根据分页参数查询用户信息，支持关键字模糊搜索") @Parameter(name = "keyword", description = "搜索关键字", example = "张三") @GetMapping("/users") public Result<List<UserVO>> listUsers(@RequestParam(required = false) String keyword) { return userService.list(keyword); }@Operation替代了Swagger 2里的@ApiOperation和@ApiImplicitParams，@Parameter替代了@ApiImplicitParam。这里的summary是接口列表中显示的名称，description是展开后的详细说明，对于接口文档的可读性来说两者都很重要。
实体模型说明：
@Schema(description = "用户信息") public class UserVO { @Schema(description = "用户ID", example = "1") private Long id; @Schema(description = "用户姓名", example = "张三") private String name; }@Schema的作用是让返回的JSON示例有具体值，而不是一堆null。这个看起来是小事，实际联调的时候帮助很大——前端不需要自己去猜字段格式，直接复制示例就能用。
分组管理：
如果你接口很多，比如后台管理系统和用户端App的接口混在同一个项目里，可以用@Tag先做逻辑分组：
@Tag(name = "用户管理", description = "用户相关接口") @RestController @RequestMapping("/users") public class UserController { }然后在配置里通过springdoc.group-configs对这些Tag做更细的归类。分组配置属于进阶操作，下面单独讲。
2.3 基于OpenAPI类的全局配置
注解是打在接口上的，但很多全局信息需要通过配置类来定义。比如文档基本信息、全局认证头等，可以这样写：
@Configuration public class OpenApiConfig { @Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title("用户服务API文档") .version("1.0.0") .description("提供用户管理相关接口") .contact(new Contact().name("研发部").email("dev@example.com"))) .components(new Components() .addSecuritySchemes("bearer-key", new SecurityScheme() .type(SecurityScheme.Type.HTTP) .scheme("bearer") .bearerFormat("JWT"))) .addSecurityItem(new SecurityRequirement().addList("bearer-key")); } }重点是addSecuritySchemes，如果你的接口需要token鉴权，加上这个配置后，Swagger UI页面会多出一个"Authorize"按钮，点进去填token，后续所有请求都会自动带上Authorization头。这个功能在联调和自测时节省大量手工填token的时间。
3. 生产环境下必须处理的三个问题：关闭、拦截器放行、环境控制
3.1 Spring Boot如何关闭SpringDoc的几种方式
网上搜"springboot怎么关闭springdoc"的人特别多，说明大家都有共识：接口文档不应该暴露在生产环境。关闭的方式有几种，我按推荐程度排序。
方式一：通过配置控制（最推荐）
springdoc: api-docs: enabled: false swagger-ui: enabled: false把这两行配置放进生产环境的配置文件里，比如application-prod.yml。这里有个细节要注意：只关swagger-ui不够，/v3/api-docs这个JSON接口依然会暴露接口结构。只有两个enabled都设为false，才能把文档的入口彻底关掉。
方式二：按环境变量控制（适合同一套配置多环境部署）
如果你不想为每个环境维护一套配置文件，可以在主配置里用占位符：
springdoc: api-docs: enabled: ${SPRINGDOC_ENABLED:true} swagger-ui: enabled: ${SPRINGDOC_ENABLED:true}生产环境部署时设置环境变量SPRINGDOC_ENABLED=false即可。这种方式更灵活，但需要维护部署脚本，适合上了CI/CD的团队。
方式三：通过代码控制（适合有复杂条件判断的场景）
@Configuration @ConditionalOnProperty(name = "springdoc.enabled", havingValue = "true", matchIfMissing = true) public class OpenApiConfig { // 配置内容 }这种方式适合需要同时控制其他Bean创建的场景，但日常使用优先级不高。
3.1.1 关闭后必须验证的点
关闭配置生效后，建议至少验证两个接口是否返回404或403：
http://localhost:8080/swagger-ui.htmlhttp://localhost:8080/v3/api-docs
这两个入口一个都不能通，才算真正关闭干净。如果你们有Spring Security，还需要在安全配置里把这两个路径加入白名单，不然SpringDoc的自动配置可能和Spring Security冲突，出现启动报错或页面样式加载不出来。
3.2 Spring Security环境下的路径放行
接入了Spring Security的项目，启动后访问Swagger页面经常会遇到白屏或者返回401，这是因为Spring Security默认拦截了所有请求，Swagger UI所需的静态资源也被挡住了。
需要在安全配置中放行以下路径：
.requestMatchers( "/swagger-ui.html", "/swagger-ui/**", "/v3/api-docs/**", "/v3/api-docs.yaml" ).permitAll()有人会问，放行/swagger-ui/**是不是意味着文档页面没有保护了？是的，但文档页面本身只是UI壳子，真正的接口数据还是受Spring Security保护的。也就是说其他人打开Swagger页面能看到接口列表，但点"Try it out"调用接口时，如果接口有鉴权，照样会返回401。所以放行Swagger UI路径本身不会造成接口泄露。
如果你的接口全部要求登录后才能调用，那么配合前面的全局bearer-key配置，在Swagger页面上把token填进去，联调流程就很顺了。
3.3 本地开发要文档、线上不需要文档的完整配置方案
实战中更合理的方式是把文档默认开启，然后在生产环境配置里强制关闭：
application.yml（默认生效）：
springdoc: swagger-ui: enabled: true api-docs: enabled: trueapplication-prod.yml（生产环境）：
springdoc: swagger-ui: enabled: false api-docs: enabled: false启动命令指定环境：
java -jar app.jar --spring.profiles.active=prod这套方案的好处是：开发者本地启动直接就能看文档，不用额外操作；持续集成环境的自动化测试如果依赖文档结构，也能正常访问；生产环境则彻底关闭，不会把接口细节暴露出去。生产环境之外的文档权限，再用Spring Security的permitAll配合内网访问策略兜底，兼顾开发和安全的平衡。
4. 给Swagger页面所有API统一添加前缀的完整解法
4.1 为什么你需要统一前缀
搜"swagger页面api添加统一前缀"这个热词的人，大概率遇到过这个场景：服务部署在网关后面，网关给所有下游服务的路由都加了一个前缀（比如/api/user-service），但Swagger页面里显示的接口路径还是原来的/user/list。前端拿着Swagger里的路径去调网关，少了个前缀直接404。
这种场景下你有两个选择：一是改所有Controller的@RequestMapping，把前缀写死进去；二是在SpringDoc层做统一处理。显然第一种方案侵入性太强，改完所有接口路径变了，Nginx和网关的路由规则都得跟着改。SpringDoc层面就要优雅得多。
4.2 配置层面给OpenAPI加前缀
SpringDoc的server配置可以直接给API文档加前缀：
springdoc: swagger-ui: enabled: true api-docs: enabled: true servers: - url: /api/user-service设置后，Swagger UI页面顶部会显示一个Server的URL，所有接口请求都会自动带上这个前缀。这个配置听起来完美，但有个坑：它仍然需要访问Swagger页面的入口路径不带前缀，也就是/swagger-ui.html还是原样访问，只是在调用接口时自动拼接前缀。如果生产环境你想把Swagger页面本身也放到前缀后面，就需要再配合网关的路由规则做一层跳转。
4.3 自己实现ServerCustomizer做动态控制（推荐）
配置写死的方式在单环境部署下没问题，但如果一套代码要部署到多个网关不同的环境，前缀是不同的（比如测试环境是/api/user-svc-test，生产环境是/api/user-svc），写死到配置文件里就得维护好多份。
更灵活的方式是实现OpenApiCustomizer接口，用代码动态注入Server：
@Component public class CustomServerCustomizer implements OpenApiCustomizer { private final UserServiceProperties properties; public CustomServerCustomizer(UserServiceProperties properties) { this.properties = properties; } @Override public void customise(OpenAPI openApi) { String prefix = properties.getGatewayPrefix(); if (StringUtils.hasText(prefix)) { openApi.servers(List.of( new Server().url(prefix) )); } } }这样网关前缀就通过配置中心的配置项来控制了，不同环境的运维只需要在配置中心改一个user-service.gateway-prefix的值，Swagger页面里的接口路径就会随之变化。前端对接时看到的路径永远和实际线上一致，不再需要人工心算补前缀。
4.4 .NET Core项目也可以这样加前缀
搜热词里还有一个"net core swagger页面api添加统一前缀"，跨领域的读者可能会搜到这里。原理和SpringDoc一样，.NET Core在Swagger中间件里配置PreSerializeFilters：
app.UseSwagger(c => { c.PreSerializeFilters.Add((swaggerDoc, httpReq) => { swaggerDoc.Servers = new List<OpenApiServer> { new OpenApiServer { Url = $"/api/user-service" } }; }); });这证明了一个通用规律：不管是Java还是.NET，只要你的API文档工具支持OpenAPI规范，就能通过修改servers数组来统一加前缀，完全不需要改Controller里的路由。架构上改文档比改接口路径要安全得多。
5. 发布后swagger.json 404问题排查与解决
5.1 404问题的常见原因定位
"vs2026 webapi 发布后 提示 not found /swagger/v1/swagger.json"这个热词包含了两个信息：一是发布后的环境，二是路径带v1的Swagger 2风格。这种404在Spring项目里也频繁出现，我把可能的原因按出现频率列一个排查表：
| 可能原因 | 判断方式 | 解决对策 |
|---|---|---|
| 生产环境通过配置关闭了文档 | 检查配置文件中swagger相关开关是否为false | 按需打开或通过配置中心动态控制 |
| Spring Security拦截 | 直接访问/v3/api-docs是否返回401 | 在安全配置中添加文档路径放行 |
| 网关路由前缀问题 | 文档页面能打开，但JSON接口404 | 确认网关是否给/v3/api-docs也加了前缀 |
| 静态资源被缓存 | 换个无痕窗口访问 | 刷新缓存或设置no-cache响应头 |
| 依赖冲突 | 项目里同时引入了Springfox和SpringDoc | 检查依赖树，移除旧版Swagger相关依赖 |
5.2 网关路径转发的专项排查
这个很容易被忽略。假设网关把/api/user-service/**转发到用户服务，而用户服务里的Swagger入口是原生路径/swagger-ui.html，你通过http://网关地址/api/user-service/swagger-ui.html访问，页面会加载出来，但页面里的JSON请求会指向http://网关地址/api/user-service/v3/api-docs，如果网关没有把/api/user-service/v3/api-docs转发到用户服务的/v3/api-docs，就404了。
这种情况有两个解法。第一个是在SpringDoc配置里把springdoc.swagger-ui.path改成带前缀的路径，让页面里的请求也带上网关前缀：
springdoc: swagger-ui: path: /api/user-service/swagger-ui.html第二个是让网关对Swagger相关路径做特殊处理，比如把/api/user-service/v3/api-docs改写到/v3/api-docs再转发。具体怎么选，取决于你的网关能力。如果网关规则不方便改，就用第一种；如果你希望所有服务的文档都能通过网关统一访问，就用第二种。
5.3 Spring Boot 2和3、Springfox和SpringDoc的版本选择
这里再强调一下容易被忽视的版本问题。很多404和启动报错其实是依赖版本选错导致的：
| 场景 | 正确依赖 | 错误示例 |
|---|---|---|
| Spring Boot 3.x + SpringDoc | org.springdoc:springdoc-openapi-starter-webmvc-ui:2.x | springdoc-openapi-ui:1.x |
| Spring Boot 2.x + SpringDoc | org.springdoc:springdoc-openapi-ui:1.6.x | springdoc-openapi-starter-webmvc-ui |
| Spring Boot 2.x + Springfox | io.springfox:springfox-boot-starter:3.0.0 | springfox-swagger2:2.9.2 |
Spring Boot 3项目如果误用了springdoc-openapi-ui 1.x版本，启动阶段就会因为Jakarta依赖问题直接报NoClassDefFoundError，根本走不到访问文档那一步。而SpringBoot 2.6以上如果继续用Springfox 2.9.2，可能会出现Failed to start bean 'documentationPluginsBootstrapper'的报错。
一个排查技巧：先看项目启动日志，如果文档相关Bean创建失败会在启动阶段直接暴露；如果能正常启动但页面打不开，才优先考虑路径和网络层问题。这样能有效缩小排查范围，不至于在路径配置上瞎折腾。
6. 新方向：Swagger转MCP，把API文档变成可调用工具
这个热词非常有前瞻性——"swagger 转mcp"。"MCP"是Model Context Protocol的缩写，简单理解，它是一种让大语言模型（比如各类AI助手）调用外部工具的标准协议。而Swagger/OpenAPI文档本质上就是对"外部工具接口"的系统化描述，所以你完全可以基于OpenAPI文档自动生成MCP服务器，让AI直接调用你的后端接口。
实践上确实已经有成熟的方案，比如python-mcp-server配合OpenAPI转换工具，或者一些MCP SDK直接把Swagger JSON文件暴露为标准工具。原理并不复杂：读取/v3/api-docs返回的JSON，解析出每个路径的HTTP方法和参数，把这些信息注册成MCP工具的输入参数，然后MCP Server在收到调用请求时，把参数组装成HTTP请求转发给你的后端服务。
这个玩法意味着你的接口文档不再只是给人看的，也能给AI消费。我建议你可以在本地先搭个demo，把/v3/api-docs的JSON内容通过一个转换脚本导入MCP Server，然后用支持MCP的客户端（比如一些AI编程工具）让AI直接"调用"你本地的接口，实际体验一下文档驱动AI接入的流程。
不过这里也提醒一句，MCP接入后相当于多了一个自动调用接口的入口，安全控制要跟上。至少要保证生产环境的/v3/api-docs关闭或鉴权，避免接口信息直接暴露给不必要的调用方。
7. 我踩过的几个坑和最后的一点实战建议
最后聊聊我实际使用SpringDoc这些日子积攒下来的一些经验。很多人以为引入依赖后一切自动化就完了，其实坑往往藏在细节里。
第一个坑是字段级别的注解覆盖。如果你的实体类字段上同时标了JSR-303的@NotNull等校验注解和@Schema，SpringDoc默认会根据@NotNull把字段标记为必填。这个逻辑本来很贴心，但如果你的DTO是复用的，同一个字段在不同接口里有不同的必填要求，就会出现在A接口必填、在B接口选填，但文档里只能显示出一种定义。处理方式是在@Schema里显式设置requiredMode = Schema.RequiredMode.NOT_REQUIRED或REQUIRED，以覆盖校验注解推断出来的值。
第二个坑是泛型和继承的解析。如果你的返回对象是多层泛型嵌套，比如Result<PageResult<UserVO>>，SpringDoc解析出来的JSON结构有时会让人摸不着头脑。这个问题的根源是Java泛型擦除和信息丢失，常规解法是确保Controller返回类型用具体的参数化类型来定义，不要返回裸的Object。如果确实需要复杂的泛型结构，可以配合@Schema(implementation = UserVO.class)手动指定。
第三个坑是文档里的内部接口泄露。Spring Boot的健康检查端点、错误处理端点（/error）、默认的错误路径都可能被扫描进文档。官方给了配置：
springdoc: paths-to-exclude: - /error - /actuator/** packages-to-scan: - com.example.controller其中paths-to-exclude从路径维度排除，packages-to-scan从代码包维度限制扫描范围。建议在实际项目中至少配置paths-to-exclude，把/error和/actuator/**排除掉，不然文档页面会多出不少无意义的端点。
最后一个是分组配置。当接口数量超过100个时，单页面的Swagger UI加载和浏览体验都会下降。SpringDoc支持把接口按维度拆成多个Group，在UI页面顶部有下拉切换：
springdoc: group-configs: - group: user packages-to-scan: com.example.controller.user - group: admin packages-to-scan: com.example.controller.admin配置完成后，Swagger UI页面会出现分组下拉框，也可以直接访问/v3/api-docs/user和/v3/api-docs/admin分别查看对应分组的JSON结构。这个功能对有多个业务模块的开发者来说特别实用，接口文档不再是一锅端。
说到底，SpringDoc是个"下限很高"的工具，你啥都不配也能用；但真正要把它用好，让文档给前端、测试、运维、甚至AI都能高效消费，还是花点心思研究下配置。建议你做完基础配置后，再去把生产环境关闭、网关前缀、分组这几个点都配置完整，这套文档基建基本就能稳定拿出手了。
