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 3springdoc-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 groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.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 ResultListUserVO listUsers(RequestParam(required false) String keyword) { return userService.list(keyword); }Operation替代了Swagger 2里的ApiOperation和ApiImplicitParamsParameter替代了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(devexample.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_ENABLEDfalse即可。这种方式更灵活但需要维护部署脚本适合上了CI/CD的团队。方式三通过代码控制适合有复杂条件判断的场景Configuration ConditionalOnProperty(name springdoc.enabled, havingValue true, matchIfMissing true) public class OpenApiConfig { // 配置内容 }这种方式适合需要同时控制其他Bean创建的场景但日常使用优先级不高。3.1.1 关闭后必须验证的点关闭配置生效后建议至少验证两个接口是否返回404或403http://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.activeprod这套方案的好处是开发者本地启动直接就能看文档不用额外操作持续集成环境的自动化测试如果依赖文档结构也能正常访问生产环境则彻底关闭不会把接口细节暴露出去。生产环境之外的文档权限再用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接口用代码动态注入ServerComponent 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中间件里配置PreSerializeFiltersapp.UseSwagger(c { c.PreSerializeFilters.Add((swaggerDoc, httpReq) { swaggerDoc.Servers new ListOpenApiServer { 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 SpringDocorg.springdoc:springdoc-openapi-starter-webmvc-ui:2.xspringdoc-openapi-ui:1.xSpring Boot 2.x SpringDocorg.springdoc:springdoc-openapi-ui:1.6.xspringdoc-openapi-starter-webmvc-uiSpring Boot 2.x Springfoxio.springfox:springfox-boot-starter:3.0.0springfox-swagger2:2.9.2Spring 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等校验注解和SchemaSpringDoc默认会根据NotNull把字段标记为必填。这个逻辑本来很贴心但如果你的DTO是复用的同一个字段在不同接口里有不同的必填要求就会出现在A接口必填、在B接口选填但文档里只能显示出一种定义。处理方式是在Schema里显式设置requiredMode Schema.RequiredMode.NOT_REQUIRED或REQUIRED以覆盖校验注解推断出来的值。第二个坑是泛型和继承的解析。如果你的返回对象是多层泛型嵌套比如ResultPageResultUserVOSpringDoc解析出来的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都能高效消费还是花点心思研究下配置。建议你做完基础配置后再去把生产环境关闭、网关前缀、分组这几个点都配置完整这套文档基建基本就能稳定拿出手了。