下午三点我把最后一个接口写完习惯性打开 Swagger 页面准备核对参数。结果接口列表空空如也中间一行刺眼的红字“No operations defined in spec!”。重启服务、清浏览器缓存、删掉浏览器里的 Swagger 数据折腾了十分钟页面照样一片空白。这种场景估计每个用 Swagger 的人多多少少都撞上过。如果你也被这行字卡住过或者现在正卡在那里可以确定一件事这基本不是 Swagger 组件本身“坏了”而是它在告诉你——文档生成链路里有一环把接口信息弄丢了。这篇文章我会按照实际排查的顺序从 Swagger 生成文档的原理开始把最常见的几种原因、对应修复办法、以及不同技术栈里的同类问题全部梳理一遍。看完你大概率能直接定位到自己项目的那一行配置。1. 报错根源Swagger 生成文档的两条链路与一个判定条件1.1 Swagger UI、OpenAPI JSON 与注解扫描的关系想搞懂这个报错先要理清 Swagger 到底是怎么把接口变成网页的。整个流程其实可以拆成两条链路一条是后端扫描接口定义生成一份 JSON 文件另一条是前端页面去加载这份 JSON渲染成文档界面。第一条链路上Swagger 的扫描器会拿到 Spring 容器里所有注册的 Handler Method也就是那些加了Controller、RestController的类中被RequestMapping、GetMapping、PostMapping等注解标记过的方法。扫描器收集到这些方法后会把它们整理成 OpenAPI 规范的结构最终输出成一份 JSON在 Springfox 较老的版本里地址是/v2/api-docs在 Springfox 3.0 或 springdoc 里通常就是/v3/api-docs。第二条链路上Swagger UI 页面启动时会通过配置好的地址去请求这份 JSON。如果请求到了就把接口列表渲染出来如果请求不到、或者 JSON 里的 paths 字段是空的页面就会显示一行提示。你看到的 “No operations defined in spec!”翻译成大白话就是我拿到你的 JSON 了但这里面一个接口操作都没有。这个细节很关键。很多人看到这行字第一反应是 Swagger UI 加载失败其实不是。“No operations”意味着 UI 是通的问题出在生成 JSON 的那道工序上——扫描器没有收集到任何接口。1.2 判定条件“operations”到底从哪里来再往深一层看Swagger 对“一个可展示的接口操作”其实是有筛选标准的。不是所有方法都会被收进文档里它要求方法上必须存在明确的路径映射注解并且所在的类要被 Spring 容器正常管理。两个条件缺一个这个方法就不会被算作一个 operation。这里有一个很容易看走眼的细节如果你把一个RequestMapping写到类上方法上只写了GetMapping或者只写了PostMapping这是最常规的写法没问题。但反过来如果你类上没有映射注解方法上只写了RequestMapping(/xxx)Swagger 也会扫描到因为它看的是方法级注解。真正会被漏掉的是那种类上写了RestController、但方法上什么映射注解都没写的类——它在 Spring 里确实算一个 Bean但不算一个接口操作Swagger 自然也不会展示它。所以看到 “No operations defined in spec!” 时心里先要有数这是扫描结果为空而不是渲染出了问题。后面所有排查动作都是在围绕“扫描器为什么没扫到东西”来展开。1.3 先确认你用的哪个实现springfox 还是 springdoc在动手改代码之前先做一件最简单也最省事的事确认你项目里用的是哪个 Swagger 实现。这一步经常被忽略但直接决定了排查方向。如果你是在 Spring Boot 项目里用 Swagger大概率是下面两种之一。一种是早年很流行的 Springfox依赖通常是io.springfox:springfox-boot-starter或者springfox-swagger2springfox-swagger-ui另一种是现在更主流的 Springdoc依赖通常是org.springdoc:springdoc-openapi-uiSpring Boot 2.x或org.springdoc:springdoc-openapi-starter-webmvc-uiSpring Boot 3.x。两者的配置风格差很多。Springfox 需要写一个Docket的BeanSpringdoc 则更倾向于“零配置”并且它天然兼容 Spring Boot 2.6 之后新的路径匹配策略。你如果连自己用的是哪个都不知道排查起来就像蒙着眼睛找钥匙。看pom.xml或build.gradle里的依赖名30 秒就能确定。下面章节里我会把这两种实现分别对应的排查点都讲到你按自己项目的情况对号入座即可。2. Controller 层最容易被忽略的低级原因注解缺失与组件扫描2.1 Controller 没被 Spring 扫描到一切注解都白搭很多人在 Swagger 配置上折腾了半天实际上问题的根源是 Controller 本身就没有被 Spring 容器管理。Swagger 的扫描器是基于 Spring 容器的容器里没有这个 BeanSwagger 就像对着空气捣蒜怎么扫都是空。最典型的情况是启动类和 Controller 不在同一个包路径下。比如你的启动类在com.example.appController 却写在com.example.controller下属的另一个目录而且没有额外配置ComponentScan那 Spring 压根不会扫描到这个 Controller接口自然也进不了 Swagger。这种情况有一个很明显的特征不仅 Swagger 里看不到接口实际访问接口地址也会 404。如果你测试一下接口根本调不通就别在 Swagger 配置上浪费时间先去查 Spring 的组件扫描配置和包结构。还有一种容易被带偏的情况有人在启动类上手动加了ComponentScan来指定扫描路径但这个路径把 Controller 所在的包漏掉了。这种写法很隐蔽因为项目其他模块运行正常只有 Swagger 界面空空如也。2.2 类注解和方法注解缺一不可假设 Spring 容器里已经有这个 Controller 了那下一步就要看注解有没有写齐。我见过不少新手写的代码如下面这样package com.example.controller; import org.springframework.web.bind.annotation.RestController; RestController public class HelloController { public String hello() { return Hello; } }这个类虽然加了RestController但hello()方法上没有GetMapping、RequestMapping之类的映射注解Spring 根本不会把它注册成一个 Web 接口。这种代码在项目启动时不会报错但 Swagger 扫描器遍历所有 Handler Method 时一个接口都找不出来于是屏幕上就是那行熟悉的 “No operations defined in spec!”。正确的做法是至少要有类级或方法级的映射注解推荐方法级写清楚 HTTP 动作RestController RequestMapping(/api) public class HelloController { GetMapping(/hello) public String hello() { return Hello; } }另外如果你的项目用的是 Springfox还建议在 Controller 类上加上Api注解来定义分组信息。虽然少了它不一定导致 “No operations”但在某些老版本中会影响文档描述展示属于顺手就能做的事Api(tags Hello 接口)。2.3 一个真实事故组件扫描范围把 Controller 排除在外有一次我帮同事排查一个项目Swagger 页面报错接口也访问不了。我看了pom.xml依赖没问题看了 Swagger 配置basePackage没错翻 Controller注解也齐全。最后打开启动类发现上面有一行额外的ComponentScanSpringBootApplication ComponentScan(basePackages com.example.common) public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }问题就在这里。加上这行配置后Spring Boot 原本默认的扫描路径被显式覆盖了扫描范围从com.example缩小到了com.example.commonController 所在的com.example.controller包不在扫描范围内。结果就是 Controller 没有被实例化所有接口都没有映射。去掉这行多余的ComponentScanSwagger 界面立刻恢复正常。这个案例给我的教训是排查 “No operations” 时第一件事不是打开 Swagger 配置类而是先确认接口本身能不能访问。如果接口 404问题一定出在 Spring 容器层只有在接口能正常访问的情况下才需要怀疑 Swagger 的扫描配置。这个判断顺序能帮你节省大量时间。3. 扫描配置失误Docket 的 apis() 和 paths() 是怎么把接口“筛没”的3.1 Docket 配置里的 basePackage 与 PathSelectors用 Springfox 的时候最典型的一种报错场景是 Docket 配置文件里写错了扫描路径。下面这段配置在无数项目里见过Configuration EnableOpenApi public class SwaggerConfig { Bean public Docket docket() { return new Docket(DocumentationType.OAS_30) .select() .apis(RequestHandlerSelectors.basePackage(com.example.control)) .paths(PathSelectors.any()) .build(); } }注意basePackage写的是com.example.control但项目里的 Controller 实际在com.example.controller包下。一个字母之差Swagger 扫描器在过滤 handler 时会把所有接口全部滤掉最终集合为空。最无语的是项目本身完全正常接口能调通Swagger 里就是一片空白。basePackage过滤的本质是扫描器在 Spring 容器中找到所有 Handler Method 后用这个包名去匹配方法所在的类。匹配不上的全部丢弃。所以这个配置不能想当然最好直接复制 Controller 所在包的路径而不是手敲。如果你不想用包路径过滤也可以直接用RequestHandlerSelectors.any()表示不限定包扫描容器里的全部接口。但这样做太宽泛生产环境容易把一些内网组件接口暴露到文档里不建议长期用。更稳妥的方式是先临时改成any()试试如果文档立刻有了接口说明就是包路径过滤的问题。3.2 paths 过滤太狠接口被“筛”出了文档paths()是另一个容易出问题的地方它过滤的是请求路径。常见的写法是这样的.apis(RequestHandlerSelectors.basePackage(com.example.controller)) .paths(PathSelectors.ant(/api/**))如果你的 Controller 里声明的路径是/hello而不是/api/hello那这个过滤条件会把所有接口都挡在文档外面。Springfox 的PathSelectors.ant(/api/**)走的是 Ant 风格路径匹配规则**能匹配多层目录但只要接口路径没有/api前缀照样不会出现在文档里。这种情况很好验证打开接口的实际地址比如http://localhost:8080/hello如果能访问但 Swagger 空那八成是 paths 过滤条件把接口路径筛掉了。解决办法要么把 paths 条件换成PathSelectors.any()要么统一接口前缀让 Controller 的类上加上RequestMapping(/api)。3.3 多 Docket 分组时的配置互相覆盖稍微复杂一点的项目会配置多个 Docket按模块拆分文档分组。比如用户模块一个组订单模块一个组。这种设计本身没问题但写法上有个常见的坑如果多个 Docket 配置类方法名重复或者一个配置类里定义了多个Bean返回DocketSpring 容器在加载时可能只保留了最后一个 Bean或者不同组的接口互相被过滤。我见过一个项目配置了三个 Docket分别指向三个包路径结果其中一组始终显示 “No operations”。查了很久才发现三个 Docket 里有一个的basePackage和另一个完全一样实际该扫描的包名写错了一个字母。这种问题容易误导人的地方在于其他分组的文档是正常的只有这一个组是空的很多人以为是 Swagger 版本问题忽略了 Docket 配置本身的笔误。如果你用的是 Springdoc分组配置比 Springfox 更清晰在 YAML 里通过springdoc.group-configs配置即可每条配置指定一个packages-to-scan。出现类似问题时先检查分组配置里packages-to-scan路径是否和实际包路径一致再看是否有多个分组配置扫描了同一个空包。4. Spring Boot 2.6 的路径匹配策略变更一个隐蔽的经典坑4.1 升级 Spring Boot 后突然 No operations 的典型症状有一种情况非常经典项目原本用 Spring Boot 2.5 和 Springfox 3.0接口文档一直好好的。后来为了某个依赖升级把 Spring Boot 版本升到了 2.6、2.7Swagger 页面突然变成 “No operations defined in spec!”或者干脆打不开控制台会报类似这样的异常java.lang.IllegalStateException: Cannot compare as both are PatternParser based这个问题在 2021 年底到 2022 年那段时间特别多因为 Spring Boot 2.6 之后用的人越来越多而 Springfox 3.0.0 已经很久不更新了两者之间出现了明显的适配断层。好多人第一反应是自己代码哪里改坏了实际上什么都没动只是 Spring Boot 的默认行为变了。4.2 根因AntPathMatcher 与 PathPatternParser 的冲突为什么 Spring Boot 升级会导致 Springfox 失效这里要扯到 Spring MVC 的路径匹配机制。在 Spring Boot 2.6 之前Spring MVC 默认用的是AntPathMatcher来解析RequestMapping里的路径模式。而 Spring Boot 2.6 起官方把默认策略换成了PathPatternParser。PathPatternParser性能更好但它和AntPathMatcher不是一套体系。Springfox 3.0.0 内部还停留在AntPathMatcher的时代。当它试图处理 Spring MVC 提供的 PathPattern 类型时会触发类型不兼容的异常或者因为匹配条件获取失败扫描器直接返回空集合。表现出来就是接口全丢“No operations defined in spec!”。关键点在于这不是 Swagger 配置写错了也不是注解漏了而是 Springfox 这个库的实现没有跟上 Spring Boot 的新版本。很多人把 Docket 配置删了又恢复、接口注解改来改去始终解决不了就是因为没意识到问题出在框架适配层。4.3 修复方案与从 springfox 迁移到 springdoc 的建议如果项目还在使用 Spring Boot 2.6 或 2.7又暂时不想大改可以临时在application.yml里强制 Spring MVC 使用老版本的路径匹配策略spring: mvc: pathmatch: matching-strategy: ant_path_matcher这样设置之后Springfox 的兼容问题通常能压下去接口文档会恢复显示。这个方案胜在改动小但本质上是在用兼容性妥协来维持一个已经停止维护的库。AntPathMatcher 本身也会在未来的 Spring Boot 版本中逐步淘汰长期看不是最优解。更推荐的做法是迁移到 Springdoc。Springdoc 从设计之初就兼容 PathPatternParser不需要额外配置而且它直接支持 OpenAPI 3 规范、支持 Spring Boot 3.xAPI 也比 Springfox 清晰很多。迁移的工作量其实不大核心替换点就三个把依赖从springfox-boot-starter换成org.springdoc:springdoc-openapi-uiSpring Boot 2.x或org.springdoc:springdoc-openapi-starter-webmvc-uiSpring Boot 3.x。删掉原来的 Docket 配置类不需要写任何配置就能自动扫描接口。如果要自定义文档标题信息改成OpenAPI类型的 Bean。注解替换Springfox 时代的Api改成TagApiModelProperty改成SchemaApiOperation改成Operation。这些注解的包名是io.swagger.core.v3.*和 Springfox 用的io.swagger.annotations.*完全不一样项目里如果用得很多需要全局替换。迁移完以后文档地址也会从原来的/swagger-ui/变成/swagger-ui.htmlJSON 地址统一为/v3/api-docs。这个差异对测试同事来说影响比较大部署的时候记得在项目文档里更新入口地址。5. 换到别的技术栈.NET 与 Python 里同样会遇到“No operations”5.1 .NET SwashbuckleMinimal API 和 Endpoint 注册很多文章在讲这个报错时都默认是 Spring Boot 的场景但这个报错在 .NET 技术栈里也会出现尤其是 .NET 6 以后开始推荐 Minimal API 的写法踩坑人数明显变多。如果用 Swashbuckle.AspNetCore最典型的“No operations”原因是漏了AddEndpointsApiExplorer()。看下面这个例子var builder WebApplication.CreateBuilder(args); builder.Services.AddSwaggerGen(); var app builder.Build(); app.UseSwagger(); app.UseSwaggerUI(); app.MapGet(/hello, () Hello); app.Run();这个代码里AddSwaggerGen()是注册了Minimal API 的接口也通过MapGet创建了但 Swagger 就是看不到/hello这个操作。原因是 Minimal API 的端点信息默认不会自动暴露给 Swagger还需要显式调用AddEndpointsApiExplorer()让框架把 Minimal API 的端点参数、返回类型等元数据收集起来。修复很简单第二行改成builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen();如果是传统 Controller 写法问题点通常在于 Controller 类缺少[ApiController]和[Route]特性或者方法上缺少[HttpGet]、[HttpPost]这类动作特性。和 Java 里的情况差不多只要方法没有明确的 HTTP 动作标记Swashbuckle 就不会把它算成一个可供文档展示的操作。另外要注意 .NET 版本的差异老版本有些完整的 Swashbuckle 配置模板被抄过来后SwaggerDoc参数里的版本号写错也会导致 UI 加载的 JSON 地址 404页面上可能显示异常或空白现象略有不同排查时也留意一下控制台网络的报错状态码。5.2 Python FastAPI“接口全写好了文档就是空”Python 生态里FastAPI 自带 Swagger UI/docs和 ReDoc/redoc底层是一份 OpenAPI JSON默认路径/openapi.json。如果是 FastAPI 项目出现类似问题最常见的场景是写了一大堆APIRouter但忘记挂载到 app 上。看这个代码from fastapi import APIRouter, FastAPI app FastAPI() router APIRouter() router.get(/items) def get_items(): return {items: []} # 忘了 app.include_router(router)路由有了接口函数也有了但router没有被 include 到app里FastAPI 生成的 OpenAPI 文档里自然就没有/items。此时/docs页面就是干干净净的“No operations defined”。另一个常见原因是自定义了openapi_url但值不对。有些项目为了隐藏接口文档把openapi_url设置成了None结果开发环境忘了调回来前端页面会提示无法加载文档。建议先访问/openapi.json确认这份 JSON 里的paths字段是否有接口数据如果paths为空优先检查include_router和各路由装饰器是否生效。Flask flask-restx 也是类似套路。api.route(/hello)挂到类上但api.add_namespace(ns)这一行被漏掉了或者Api(app)没有与路由建立关联都会导致文档列表空白。这类问题的排查思路是通用的先看数据源OpenAPI JSON 或类似的 API 描述文件里有没有接口再回头看路由注册逻辑。6. 快速定位法从接口地址开始逐层排查6.1 第一招直达 OpenAPI JSON分清“UI 问题”还是“扫描问题”遇到 “No operations defined in spec!”别急着改配置先用最直接的办法把问题分成两类。打开浏览器直接访问 Swagger UI 背后的 JSON 地址看看里面到底有没有数据。Springfox 2.x 访问/v2/api-docsSpringfox 3.0 和 springdoc 访问/v3/api-docsFastAPI 访问/openapi.json。比如 Spring Boot 项目在本地启动地址就是http://localhost:8080/v3/api-docs如果你看到 JSON 里paths字段是空的{}说明扫描链路有问题重点排查 Controller 注解、组件扫描、Docket 配置这些内容。如果paths里有接口数据但 Swagger UI 页面还是显示 “No operations”那问题就出在前端加载环节需要检查 Swagger UI 的配置地址是否正确、是否配了错误的 group、浏览器是否有缓存。实际工作中绝大多数报错都集中在第一种——paths直接是空的。6.2 第二招用 Actuator 或日志确认接口到底进没进容器如果 JSON 里是空的下一步要回答一个问题这个接口在 Spring 容器里到底有没有注册不要靠猜直接用工具确认。最省事的办法是引入 Spring Boot Actuator 的mappings端点。在pom.xml中加入依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-actuator/artifactId /dependency然后在application.yml里暴露配置management: endpoints: web: exposure: include: mappings重启后访问http://localhost:8080/actuator/mappings能看到所有已注册的 URL 映射。如果你在这里能看到/hello说明接口已经进入 Spring MVC 的映射表问题十有八九出在 Swagger 扫描过滤条件上如果这里也没有/hello说明接口根本没注册成功Swagger 这边再怎么配也没用得回头查组件扫描或注解。还有一种更轻量的方式看启动日志。Spring Boot 启动时会打印一部分 RequestMapping 信息但默认格式不一定直观。如果没有 Actuator也可以临时加一个CommandLineRunner打印接口列表。不过说实话Actuator 最省力建议直接用。6.3 第三招剥离干扰的排错顺序与检查清单当问题集中到扫描链路之后排错要按顺序来不要同时改几个地方不然无法判断是哪一项生效了。推荐按这个顺序操作第一临时把 Docket 配置里的basePackage换成RequestHandlerSelectors.any()重启看一眼文档是否有数据。如果有说明是包路径过滤的问题如果还是没有继续下一步。第二检查 Controller 类上有没有RestController或Controller方法上有没有GetMapping、PostMapping、RequestMapping等映射注解。随便找一个最简单的接口方法确保接口能直接通过浏览器访问到。第三检查启动类所在包和 Controller 所在包的关系。如果两者不在同一个根包下确认是否存在合理的ComponentScan配置。第四确认 Spring Boot 版本和 Swagger 实现的兼容性。如果 Spring Boot 2.6 配 Springfox直接把spring.mvc.pathmatch.matching-strategy设置成ant_path_matcher验证一次是否能恢复正常。第五如果以上都没问题检查是否有多段 Docket 配置互相干扰或者依赖中同时引入了多个 Swagger 相关包导致版本冲突。比如springfox-swagger2和springfox-boot-starter同时存在时Bean 加载顺序可能会有问题。把这五步走完绝大多数 “No operations” 都能定位出来。说到底这行报错不是 Swagger 在为难你它只是诚实地把“扫描结果为空”这件事亮了出来。与其反复重启试运气不如按这条链路一层层排除通常十分钟内就能找到问题所在。