把Swagger换成SpringDoc之后我的接口文档再也没在产品会上被当众打脸。别误会Swagger不是不好而是它停在2.0时代太久。2026年做新项目SpringDoc几乎已经是Spring Boot社区里写接口文档的默认选项它直接挂在OpenAPI 3.0/3.1规范上和Spring Boot 3/4的兼容性也最好。这篇指南就是写给那些还在纠结“到底用不用Swagger”“springfox还能不能撑下去”“文档导出Excel坏了怎么办”的人我会从选型、集成、注解、安全认证、外部接口、离线导出一路讲到最后顺手把最近群里反复问的导出Excel损坏问题也一起拆了。1. 为什么是SpringDoc2026年接口文档选型的几个硬道理先说结论只要你是Spring Boot新项目2026年我找不到一个理由去用回springfox。SpringDoc不是“更时髦”的Swagger它是站在OpenAPI 3规范上重新做的一套运行时文档生成器解决的是旧工具在Spring Boot 3之后活不下去的问题。1.1 Springfox停更带来的连锁反应Springfox最后一个稳定版本大概是2020年前后之后就进入了修修补补也不一定能跑的状态。Spring Boot 2.x时代它还能靠着各种“兼容补丁”硬撑但到了Spring Boot 3springfox直接卡在javax包迁移上。Spring Boot 3全家桶用的是jakarta命名空间而springfox的核心代码全是基于javax的除非有人持续做适配否则它就是一堆运行时反射错误。很多老项目不是不想升是每次把Spring Boot升到3.xSwagger UI先挂。我见过一个团队为了保住接口文档硬是让新服务停留在Spring Boot 2.7半年。这就是典型的工具绑架业务。SpringDoc之所以能接盘是因为它从设计上就跟着OpenAPI 3规范走并且主动适配Spring Boot 3的Jakarta体系升级路径干净得多。1.2 先搞清楚Swagger、OpenAPI、SpringDoc谁是爹这里顺便把概念理一理因为很多人混着叫。OpenAPI是一份接口描述规范它定义了paths、components、securitySchemes这些JSON结构。Swagger最早是围绕这套规范做出来的那套工具链的名字包括Swagger UI、Swagger Editor、Swagger Codegen。SpringDoc则是一个运行时库它扫描Spring MVC的注解和代码结构生成一份符合OpenAPI格式的JSON文档然后自动挂一个Swagger UI前端页面。所以你看到的“Swagger页面”其实是Swagger UI背后喂数据给它的在Spring Boot项目里往往就是SpringDoc。SpringDoc本身并不发明一套新UI它复用Swagger UI只是换掉了旧版的数据生成引擎。1.3 选型对照不要无脑换也别死守工具支持的规范维护状态适合场景SpringDocOpenAPI 3.0 / 3.1活跃新项目Spring Boot 3Java 17springfoxSwagger 2.0基本停更老项目短期过渡能不碰别碰Knife4j4.x底层还是SpringDoc活跃想要国产增强UI和离线文档的团队Apifox/Postman不限外部服务团队协作、Mock、联调替代内嵌文档Knife4j不是一个替代SpringDoc的框架它更像SpringDoc的一件“皮肤”底层帮你管理SpringDoc依赖。如果你只是喜欢它的UI可以单独引入Knife4j但依赖坐标仍然会落到SpringDoc上。这也是为什么网上问“Knife4j导出Excel坏了”的人根因排查到最后总是绕回SpringDoc和POI的兼容问题后面我会单独讲。2. Spring Boot 3.4集成SpringDoc一套能直接复制的最小配置集成过程其实比想象中简单但网上的教程版本参差不齐很多还停留在旧包名。2026年正确的坐标是springdoc-openapi-starter-webmvc-ui注意是starter开头旧版的springdoc-openapi-ui已经不再推荐。2.1 依赖引入普通MVC项目只加一个坐标如果你用的是Maven在pom.xml里加这段dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.8.0/version /dependency项目基于WebFlux的话artifactId要换成springdoc-openapi-starter-webflux-ui。千万别两个一起引我见过有人为了兼容硬塞了三个不同版本的SpringDoc最后启动直接bean冲突。这里多说一句版本选择。你去看中央仓库SpringDoc版本号已经从2.6一路走到2.8甚至更高不同版本对Spring Boot的小版本很敏感。最简单的方法是去SpringDoc官方GitHub的README里看Compatibility矩阵不要闭眼升到最高版。我自己的习惯是锁定某个大版本内的最新小版本比如2.8.x等Spring Boot小版本升级稳定后再观察SpringDoc是否有对应补丁。2.2 配置文件里的关键项集成后默认就能用但不配置一下会很难受。我常用这份YAMLspringdoc: api-docs: enabled: true path: /v3/api-docs swagger-ui: path: /swagger-ui.html display-request-duration: true operations-sorter: method tags-sorter: alpha packages-to-scan: com.example.demo.controller paths-to-match: /api/** default-produces-media-type: application/json cache: disabled: truedisplay-request-duration会在UI上显示每个接口的耗时联调时特别有用。operations-sorter按HTTP方法排序POST、GET这些不再乱序截图给前端好看很多。cache.disabledtrue是为了开发环境下修改代码后Swagger UI里的文档不缓存旧版本。生产环境我建议把这个开关关掉否则每次有请求都重新生成OpenAPI JSON压力白增。2.3 启动后先验证这三件事启动项目以后不要急着写注解先访问下面三个地址/swagger-ui.html最终会重定向到/swagger-ui/index.html页面能打开说明静态资源没问题。/v3/api-docs能看到一大段JSON这是Swagger UI的数据源。/v3/api-docs.yamlSpringDoc 2.x之后直接导出YAML格式。如果你发现UI一直转圈打开浏览器DevTools看Network大概率是/v3/api-docs请求被Spring Security拦成401了。如果是接口列表空白但JSON里有数据多半是Controller没有加RestController只加Controller时SpringDoc不认。提示packages-to-scan不是必填项。不加的话SpringDoc默认扫描启动类所在包及子包。只有当你需要把多个模块拼接在一个项目里时才显式声明。3. 注解怎么写才不浪费把接口文档从“能看”提升到“能用”很多人集成完SpringDoc就把活停了觉得页面上已经有接口列表就行。但实际开发中一张只有路径和参数名的文档基本等于没法用。真正有价值的接口文档要能回答三个问题这个接口是干什么的、参数有什么约束、出错会返回什么。3.1 一组最常用的注解搭配我通常在每个接口上写这样一组注解Operation( summary 查询用户列表, description 分页查询用户支持按姓名和状态过滤sort字段格式如createTime,desc ) Parameters({ Parameter(name page, description 页码从1开始, example 1), Parameter(name size, description 每页条数最大100, example 20) }) ApiResponse(responseCode 200, description 查询成功, content Content(schema Schema(implementation PageResult.class))) ApiResponse(responseCode 400, description 参数不合法, content Content(schema Schema(implementation ErrorResult.class))) GetMapping(/list) public ResultPageResultUserVO list(Valid UserQuery query) { return userService.list(query); }summary一定要写人话不要说“根据id数组查询列表支持sort”而是说“按用户ID批量查询用户的基本信息”。UI上摘要列表页显示的就是summary太笼统的话前端根本不知道什么时候该调这个接口。description可以写完整规则包括字段含义、排序格式、分页上限这些都是调试时一次又一次私聊问你的东西。3.2 用ApiResponse把错误码收口很多项目的文档里只有200成功响应错误码全靠猜。实践下来最省事的做法是定义统一的ErrorResult然后用ApiResponse配三段基础错误码体系400参数错误、401未认证、403无权限、500服务异常。如果在Controller里统一处理了业务异常再加一个4001、4002这类业务码并写清触发条件。注意SpringDoc对ApiResponse的数量没有限制但写太多会刷屏。我习惯只写关键的几个其它走全局基础文案。如果你用了全局异常处理器可以考虑在OpenAPI的info.description里写一段错误码说明页面主页直接可读。3.3 DTO的Field级说明与枚举约束与其把所有描述堆在方法上不如把字段说明下沉到DTOpublic class UserQuery { Schema(description 用户姓名模糊匹配, example 张三) private String name; Schema(description 用户状态, allowableValues ENABLED, DISABLED, LOCKED) private UserStatus status; }example比description更容易被人记住。比如pageSize的example写20别人接口调试时能直接复制。枚举类型如果不加任何约束Swagger UI显示的就是Java枚举的Enum前端根本不知道传active还是ACTIVE。我碰到过正式环境因为枚举大小写问题被调了半天最后发现前端看着文档传的全是小写。所以给枚举字段加allowableValues或者用Schema明确标注最安全。3.4 多模块项目怎么分组项目大了以后一个Swagger页面里堆几十个Controller就是灾难。SpringDoc支持用GroupedOpenApi做分组Bean public GroupedOpenApi userApi() { return GroupedOpenApi.builder() .group(用户中心) .packagesToScan(com.example.controller.user) .build(); } Bean public GroupedOpenApi orderApi() { return GroupedOpenApi.builder() .group(订单中心) .packagesToScan(com.example.controller.order) .build(); }此时Swagger UI右上角会出现下拉分组每个分组一套独立的文档。对接方只需要看自己关心的一组不用面对全量接口。分组的同时也要注意路径前缀不能被扫重比如用户中心的Controller都是/api/v1/user/...那可以在builder里加pathsToMatch(/api/v1/user/**)双重保险。4. 带认证的接口文档Spring Security JWT的配置方案接口文档如果不处理认证调试体验会非常糟糕每次请求都要把token手动粘到Auth头里粘错了又得重新登录。好在SpringDoc原生支持OpenAPI的SecurityScheme配置以后Swagger UI页面右上角就会有一个Authorize按钮。4.1 先看你遇到的是不是这个现象默认情况下Spring Boot集成了Spring Security后Swagger UI能打开但所有接口都返回401。而且Swagger UI页面上没有输入token的地方。原因很简单SpringDoc生成了OpenAPI JSON但JSON里没有任何security定义请它对每个接口是否需要认证一无所知。4.2 用SecurityScheme定义JWT认证方式在OpenAPI配置Bean里加上这一段Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title(订单后台API) .version(v2.3.0) .description(内含外部依赖说明见首页链接)) .addSecurityItem(new SecurityRequirement().addList(BearerAuth)) .components(new Components().addSecuritySchemes(BearerAuth, new SecurityScheme() .type(SecurityScheme.Type.HTTP) .scheme(bearer) .bearerFormat(JWT))); }addSecurityItem里的SecurityRequirement表示所有接口默认都要带认证。如果想给某个匿名接口开例外可以在接口方法上用SecurityRequirement(name )。这个操作很细节很多团队不写导致Swagger UI把所有接口都标成带锁哪怕登录接口本身不需要token。部署到生产时我建议通过springdoc.info.description把登录接口的调用说明写在文档里避免第一次接触的人不知道去哪里拿token。4.3 Spring Security放行路由的边界配置授权时一个常见的坏习惯是把/swagger-ui/**整段放行然后忘了/v3/api-docs。正确的是把两个都放行http.authorizeHttpRequests(auth - auth .requestMatchers( /swagger-ui.html, /swagger-ui/**, /v3/api-docs/** ).permitAll() .anyRequest().authenticated() );还有一点容易踩坑Spring Security开启CSRF后Swagger UI里调试POST、PUT接口会一直403因为在页面里发请求没有带CSRF Token。开发环境可以在安全链里对swagger路径关掉CSRF。生产环境如果接口文档不开放给外部最好直接把整个文档模块通过Profile或配置开关控制在开发环境可见不要裸奔到公网。4.4 调试时自动带token的正确姿势配置好SecurityScheme后点Swagger UI右上角的Authorize输入Bearer 实际token之后所有接口请求都会自动带上Authorization: Bearer ...头。有一点得留意bearerFormat(JWT)只是给UI做展示它不会真的校验你的token格式。如果你用的是OAuth2 client credentials也可以用SecurityScheme.Type.OAUTH2那要看SpringDoc的OAuth2配置段落比JWT复杂不少。我们在内部环境里还做过一个小优化开发环境自动创建一个测试用户Swagger UI打开时默认从后端的Mock接口拿一个有效token填进去这样前端联调时连登录步骤都省了。这个思路不一定要学但能明显减少“文档能看不能调”的时间。5. 把第三方HTTP接口云MAS平台短信也纳入文档体系SpringDoc扫描的是自己项目里的Controller对外部接口它无能为力。但我们在实际项目中对接了大量第三方HTTP接口最典型的就是各种短信网关。比如我接过的云MAS平台官方提供的HTTP接口文档还是传统的Word/PDF参数说明和签名规则分散在多个文件里前端、后端、测试各存一份经常对不上。5.1 外部接口文档到底乱在哪第三方接口文档常见三宗罪第一签名算法描述不清比如MD5还是HMAC-SHA256大小写转换规则不写第二响应码表不全很多平台只给你成功场景的JSON失败返回全靠试第三字段可空性乱标文档写“手机号必填”实际调用时又要求带区号临时找客服才问到。这些坑靠人传人特别容易丢。我接手旧项目时经常看到对接短信的代码里写了一堆魔法数字旁边注释是“平台说这样传”。后来我决定把外部依赖也纳入自己的文档体系但不用SpringDoc硬扫。5.2 我的做法外部依赖说明Endpoint externalDocsSpringDoc的OpenAPI对象支持externalDocs这是一个可以挂链接和描述的地方。我把所有外部接口的完整说明整理成Markdown放在仓库的docs/external-api/目录下然后在SpringDoc的配置里把链接写进主页.info(new Info().description( 外部接口文档入口: [云MAS短信平台](https://docs.example.com/internal/sms-platform) )) .externalDocs(new ExternalDocumentation() .description(外部依赖统一说明) .url(https://docs.example.com/external-api/));同时项目里真正发短信的代码全部收敛到一个SmsClient里这个类内部写好JavaDoc和入参DTODTO字段上使用Schema(description 对应平台参数mobile)。这样虽然Swagger UI不会扫到SmsClient但它内部的字段描述会随着依赖打包进项目排查问题时能快速对齐。5.3 排障时的真实作用有一次生产环境批量发短信失败消息平台上显示“签名错误”。后端看日志发现我们的SmsClient已经把timestamp拼成了小写而平台要求大写因为我们在DTO字段描述里写清了“timestamp必须为大写字符串”前端按照文档传参后端按文档校验五分钟就定位到了不再靠翻聊天记录。如果当时只有一个对外暴露的Swagger页面第三方平台的签名细节根本没人看得见。这个思路的本质是SpringDoc不是万能的外接文档工具但它可以作为团队内部所有接口说明的聚合入口。内部接口用注解实时生成外部接口用在线文档链接挂载大家至少在同一个首页里找到所有需要的信息。6. 导出离线文档时“Excel损坏”的排查过程最近群里不止一个人遇到同一个问题从接口文档页面导出Excel拿回来双击Excel提示“文件格式和扩展名不匹配”甚至直接报损坏。这事儿在百度上一搜一大串但很多回答只告诉你“换个浏览器”“重新下载”没解决根因。6.1 先还原一下现场客户或测试需要一份离线接口清单于是有同事打开Knife4j或Swagger UI的导出功能选择导出Excel得到一个.xls文件。双击后Excel弹出警告点“是”能看到内容偶尔还出现乱码。如果是用WPS情况更怪有时能开但格式全错。6.2 排查链路第一眼看文件头这个故障最好不要在Excel里反复打开而是先看文件到底是不是真正的Excel。Linux和macOS直接执行file /tmp/api-docs.xlsWindows可以用Notepad或HxD打开文件看前几个字节。真正的.xls文件头应该以D0 CF 11 E0开头这是OLE2复合文档的固定魔数如果是504B0304那是xlsx如果你看到的是3C 21 44 4F 43 54 59 50很遗憾这其实是个HTML文件。6.3 损坏的根因导出功能名不副实排查到最后大多数“Swagger导出Excel损坏”的由来是离线导出组件没有真的生成Excel二进制文件而是生成了一张HTML表格然后强制把扩展名写成.xls。Excel为了兼容老网页导出的HTML表格通常会弹一个“格式不匹配”的警告。如果HTML里的表格结构不完整或者包含大量带转义的JSON示例Excel解析时就会直接判定文件损坏。还有一类情况是Knife4j的导出依赖POI。如果项目里已经引入了其他版本的POI或者二进制库被Shading打包搞坏导出线程运行时报错前端拿到的是部分生成的半截文件。这种你会在浏览器Network面板里看到导出接口返回了500或者响应Content-Length异常。6.4 离线文档的稳定导出路线我自己已经不指望页面上的导出Excel按钮了。稳定做法是先拿到OpenAPI JSON再按需转换访问/v3/api-docs把JSON保存为openapi.json。需要YAML时访问/v3/api-docs.yaml。需要给客户看完整页面时用Redoc或Swagger UI的静态托管生成离线的HTML单文件。确实需要Excel时用脚本解析openapi.json自己生成一份干净的表格不要依赖导出插件。下面这个Python小脚本可以快速把path和method整理成CSVimport json import csv with open(openapi.json, r, encodingutf-8) as f: data json.load(f) rows [] for path, methods in data[paths].items(): for method, op in methods.items(): rows.append([ method.upper(), path, op.get(summary, ), op.get(operationId, ) ]) with open(api-list.csv, w, newline, encodingutf-8-sig) as f: writer csv.writer(f) writer.writerow([Method, Path, Summary, OperationId]) writer.writerows(rows)这样生成的CSV可以用Excel直接打开再另存为xlsx不会出现任何“损坏”警告。如果你必须用Knife4j导出建议给文档组单独准备一个环境避免POI依赖和生产项目相互污染。7. SpringDoc还能再往前一步把文档变成回归测试的一部分集成SpringDoc之后文档和代码是同源的这一步已经赢了大多数手写Word的项目。但文档和实现仍然可能“悄悄漂移”比如你重构了RequestParam的名字代码没编译错Swagger页面上的参数却变了对讲方还拿着旧文档调半天。要让文档不骗人最好把文档也纳入自动化检查。7.1 把OpenAPI JSON当契约文件纳入版本管理现在很多团队都是启动项目才生成文档没有一份可以审阅的静态契约。我建议每次版本发布前导出一份openapi.json提交到Git。这样代码review的时候文档变更也是diff的一部分。前端对接一版接口可以直接基于这份JSON生成TypeScript客户端减少同步成本。7.2 用openapi-diff查破坏性变更社区里有现成的openapi-diff工具可以比较两份OpenAPI JSON之间所有兼容性变化。比如“把一个必填参数改成可选”是向后兼容的而“删除一个接口”“改参数名”“把必填参数删掉”是破坏性的。把它接入CIopenapi-diff old-openapi.json new-openapi.json --fail-on-incompatibleCI失败团队负责人就会去找是谁改了接口没通知下游。这比“你说你改了但前端没看到”要好太多。7.3 在集成测试里校验文档基本健康度我自己在项目里跑的一套基础校验就是三个断言Test void swaggerDocsShouldBeHealthy() throws Exception { mockMvc.perform(get(/v3/api-docs)) .andExpect(status().isOk()) .andExpect(jsonPath($.openapi).exists()) .andExpect(jsonPath($.paths).isNotEmpty()); }别小看这个测试它至少能拦住“接口文档挂掉”“路径被Security拦截”“SpringDoc配置被覆盖”这类低级问题。再进一步可以断言每个operationId唯一、每个路径都有至少一个response。这些用一个小脚本就能扫出来规则不要定太多否则后续维护会变成负担。7.4 不要为了自动化把文档写成天书自动化校验解决的是“文档和代码不一致”但解决不了“描述写得太烂”。我的经验是文档注释应该控制在“接口做什么、参数边界、错误码含义”三个粒度。不要每一个getter都写一段长篇说明那只会让重要信息沉没。把时间花在哪几个字段上就是那些让前端反复问你的字段格式、枚举值、可空性、长度限制。最后分享一个我坚持了很久的习惯我踩过太多文档坑之后养成了一个习惯每次上线前都手动看一眼/v3/api-docs.yaml从第一行滚到资源列表确认没有莫名其妙多出来的端点也没有被隐藏掉的异常状态。然后再跑一次openapi-diff把破坏性变更在测试环境就拦住。SpringDoc本身不是什么神奇框架它只是把“接口文档”从一个静态交付物变成了和代码绑定的活物真正让它值钱的是你愿不愿意像维护代码一样去维护文档。如果你是第一次在一个老项目里接它记得先备份当前Swagger页面截图后面再也不用为文档吵嘴架了。
把Swagger换成SpringDoc之后我的接口文档再也没在产品会上被当众打脸。别误会Swagger不是不好而是它停在2.0时代太久。2026年做新项目SpringDoc几乎已经是Spring Boot社区里写接口文档的默认选项它直接挂在OpenAPI 3.0/3.1规范上和Spring Boot 3/4的兼容性也最好。这篇指南就是写给那些还在纠结“到底用不用Swagger”“springfox还能不能撑下去”“文档导出Excel坏了怎么办”的人我会从选型、集成、注解、安全认证、外部接口、离线导出一路讲到最后顺手把最近群里反复问的导出Excel损坏问题也一起拆了。1. 为什么是SpringDoc2026年接口文档选型的几个硬道理先说结论只要你是Spring Boot新项目2026年我找不到一个理由去用回springfox。SpringDoc不是“更时髦”的Swagger它是站在OpenAPI 3规范上重新做的一套运行时文档生成器解决的是旧工具在Spring Boot 3之后活不下去的问题。1.1 Springfox停更带来的连锁反应Springfox最后一个稳定版本大概是2020年前后之后就进入了修修补补也不一定能跑的状态。Spring Boot 2.x时代它还能靠着各种“兼容补丁”硬撑但到了Spring Boot 3springfox直接卡在javax包迁移上。Spring Boot 3全家桶用的是jakarta命名空间而springfox的核心代码全是基于javax的除非有人持续做适配否则它就是一堆运行时反射错误。很多老项目不是不想升是每次把Spring Boot升到3.xSwagger UI先挂。我见过一个团队为了保住接口文档硬是让新服务停留在Spring Boot 2.7半年。这就是典型的工具绑架业务。SpringDoc之所以能接盘是因为它从设计上就跟着OpenAPI 3规范走并且主动适配Spring Boot 3的Jakarta体系升级路径干净得多。1.2 先搞清楚Swagger、OpenAPI、SpringDoc谁是爹这里顺便把概念理一理因为很多人混着叫。OpenAPI是一份接口描述规范它定义了paths、components、securitySchemes这些JSON结构。Swagger最早是围绕这套规范做出来的那套工具链的名字包括Swagger UI、Swagger Editor、Swagger Codegen。SpringDoc则是一个运行时库它扫描Spring MVC的注解和代码结构生成一份符合OpenAPI格式的JSON文档然后自动挂一个Swagger UI前端页面。所以你看到的“Swagger页面”其实是Swagger UI背后喂数据给它的在Spring Boot项目里往往就是SpringDoc。SpringDoc本身并不发明一套新UI它复用Swagger UI只是换掉了旧版的数据生成引擎。1.3 选型对照不要无脑换也别死守工具支持的规范维护状态适合场景SpringDocOpenAPI 3.0 / 3.1活跃新项目Spring Boot 3Java 17springfoxSwagger 2.0基本停更老项目短期过渡能不碰别碰Knife4j4.x底层还是SpringDoc活跃想要国产增强UI和离线文档的团队Apifox/Postman不限外部服务团队协作、Mock、联调替代内嵌文档Knife4j不是一个替代SpringDoc的框架它更像SpringDoc的一件“皮肤”底层帮你管理SpringDoc依赖。如果你只是喜欢它的UI可以单独引入Knife4j但依赖坐标仍然会落到SpringDoc上。这也是为什么网上问“Knife4j导出Excel坏了”的人根因排查到最后总是绕回SpringDoc和POI的兼容问题后面我会单独讲。2. Spring Boot 3.4集成SpringDoc一套能直接复制的最小配置集成过程其实比想象中简单但网上的教程版本参差不齐很多还停留在旧包名。2026年正确的坐标是springdoc-openapi-starter-webmvc-ui注意是starter开头旧版的springdoc-openapi-ui已经不再推荐。2.1 依赖引入普通MVC项目只加一个坐标如果你用的是Maven在pom.xml里加这段dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.8.0/version /dependency项目基于WebFlux的话artifactId要换成springdoc-openapi-starter-webflux-ui。千万别两个一起引我见过有人为了兼容硬塞了三个不同版本的SpringDoc最后启动直接bean冲突。这里多说一句版本选择。你去看中央仓库SpringDoc版本号已经从2.6一路走到2.8甚至更高不同版本对Spring Boot的小版本很敏感。最简单的方法是去SpringDoc官方GitHub的README里看Compatibility矩阵不要闭眼升到最高版。我自己的习惯是锁定某个大版本内的最新小版本比如2.8.x等Spring Boot小版本升级稳定后再观察SpringDoc是否有对应补丁。2.2 配置文件里的关键项集成后默认就能用但不配置一下会很难受。我常用这份YAMLspringdoc: api-docs: enabled: true path: /v3/api-docs swagger-ui: path: /swagger-ui.html display-request-duration: true operations-sorter: method tags-sorter: alpha packages-to-scan: com.example.demo.controller paths-to-match: /api/** default-produces-media-type: application/json cache: disabled: truedisplay-request-duration会在UI上显示每个接口的耗时联调时特别有用。operations-sorter按HTTP方法排序POST、GET这些不再乱序截图给前端好看很多。cache.disabledtrue是为了开发环境下修改代码后Swagger UI里的文档不缓存旧版本。生产环境我建议把这个开关关掉否则每次有请求都重新生成OpenAPI JSON压力白增。2.3 启动后先验证这三件事启动项目以后不要急着写注解先访问下面三个地址/swagger-ui.html最终会重定向到/swagger-ui/index.html页面能打开说明静态资源没问题。/v3/api-docs能看到一大段JSON这是Swagger UI的数据源。/v3/api-docs.yamlSpringDoc 2.x之后直接导出YAML格式。如果你发现UI一直转圈打开浏览器DevTools看Network大概率是/v3/api-docs请求被Spring Security拦成401了。如果是接口列表空白但JSON里有数据多半是Controller没有加RestController只加Controller时SpringDoc不认。提示packages-to-scan不是必填项。不加的话SpringDoc默认扫描启动类所在包及子包。只有当你需要把多个模块拼接在一个项目里时才显式声明。3. 注解怎么写才不浪费把接口文档从“能看”提升到“能用”很多人集成完SpringDoc就把活停了觉得页面上已经有接口列表就行。但实际开发中一张只有路径和参数名的文档基本等于没法用。真正有价值的接口文档要能回答三个问题这个接口是干什么的、参数有什么约束、出错会返回什么。3.1 一组最常用的注解搭配我通常在每个接口上写这样一组注解Operation( summary 查询用户列表, description 分页查询用户支持按姓名和状态过滤sort字段格式如createTime,desc ) Parameters({ Parameter(name page, description 页码从1开始, example 1), Parameter(name size, description 每页条数最大100, example 20) }) ApiResponse(responseCode 200, description 查询成功, content Content(schema Schema(implementation PageResult.class))) ApiResponse(responseCode 400, description 参数不合法, content Content(schema Schema(implementation ErrorResult.class))) GetMapping(/list) public ResultPageResultUserVO list(Valid UserQuery query) { return userService.list(query); }summary一定要写人话不要说“根据id数组查询列表支持sort”而是说“按用户ID批量查询用户的基本信息”。UI上摘要列表页显示的就是summary太笼统的话前端根本不知道什么时候该调这个接口。description可以写完整规则包括字段含义、排序格式、分页上限这些都是调试时一次又一次私聊问你的东西。3.2 用ApiResponse把错误码收口很多项目的文档里只有200成功响应错误码全靠猜。实践下来最省事的做法是定义统一的ErrorResult然后用ApiResponse配三段基础错误码体系400参数错误、401未认证、403无权限、500服务异常。如果在Controller里统一处理了业务异常再加一个4001、4002这类业务码并写清触发条件。注意SpringDoc对ApiResponse的数量没有限制但写太多会刷屏。我习惯只写关键的几个其它走全局基础文案。如果你用了全局异常处理器可以考虑在OpenAPI的info.description里写一段错误码说明页面主页直接可读。3.3 DTO的Field级说明与枚举约束与其把所有描述堆在方法上不如把字段说明下沉到DTOpublic class UserQuery { Schema(description 用户姓名模糊匹配, example 张三) private String name; Schema(description 用户状态, allowableValues ENABLED, DISABLED, LOCKED) private UserStatus status; }example比description更容易被人记住。比如pageSize的example写20别人接口调试时能直接复制。枚举类型如果不加任何约束Swagger UI显示的就是Java枚举的Enum前端根本不知道传active还是ACTIVE。我碰到过正式环境因为枚举大小写问题被调了半天最后发现前端看着文档传的全是小写。所以给枚举字段加allowableValues或者用Schema明确标注最安全。3.4 多模块项目怎么分组项目大了以后一个Swagger页面里堆几十个Controller就是灾难。SpringDoc支持用GroupedOpenApi做分组Bean public GroupedOpenApi userApi() { return GroupedOpenApi.builder() .group(用户中心) .packagesToScan(com.example.controller.user) .build(); } Bean public GroupedOpenApi orderApi() { return GroupedOpenApi.builder() .group(订单中心) .packagesToScan(com.example.controller.order) .build(); }此时Swagger UI右上角会出现下拉分组每个分组一套独立的文档。对接方只需要看自己关心的一组不用面对全量接口。分组的同时也要注意路径前缀不能被扫重比如用户中心的Controller都是/api/v1/user/...那可以在builder里加pathsToMatch(/api/v1/user/**)双重保险。4. 带认证的接口文档Spring Security JWT的配置方案接口文档如果不处理认证调试体验会非常糟糕每次请求都要把token手动粘到Auth头里粘错了又得重新登录。好在SpringDoc原生支持OpenAPI的SecurityScheme配置以后Swagger UI页面右上角就会有一个Authorize按钮。4.1 先看你遇到的是不是这个现象默认情况下Spring Boot集成了Spring Security后Swagger UI能打开但所有接口都返回401。而且Swagger UI页面上没有输入token的地方。原因很简单SpringDoc生成了OpenAPI JSON但JSON里没有任何security定义请它对每个接口是否需要认证一无所知。4.2 用SecurityScheme定义JWT认证方式在OpenAPI配置Bean里加上这一段Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title(订单后台API) .version(v2.3.0) .description(内含外部依赖说明见首页链接)) .addSecurityItem(new SecurityRequirement().addList(BearerAuth)) .components(new Components().addSecuritySchemes(BearerAuth, new SecurityScheme() .type(SecurityScheme.Type.HTTP) .scheme(bearer) .bearerFormat(JWT))); }addSecurityItem里的SecurityRequirement表示所有接口默认都要带认证。如果想给某个匿名接口开例外可以在接口方法上用SecurityRequirement(name )。这个操作很细节很多团队不写导致Swagger UI把所有接口都标成带锁哪怕登录接口本身不需要token。部署到生产时我建议通过springdoc.info.description把登录接口的调用说明写在文档里避免第一次接触的人不知道去哪里拿token。4.3 Spring Security放行路由的边界配置授权时一个常见的坏习惯是把/swagger-ui/**整段放行然后忘了/v3/api-docs。正确的是把两个都放行http.authorizeHttpRequests(auth - auth .requestMatchers( /swagger-ui.html, /swagger-ui/**, /v3/api-docs/** ).permitAll() .anyRequest().authenticated() );还有一点容易踩坑Spring Security开启CSRF后Swagger UI里调试POST、PUT接口会一直403因为在页面里发请求没有带CSRF Token。开发环境可以在安全链里对swagger路径关掉CSRF。生产环境如果接口文档不开放给外部最好直接把整个文档模块通过Profile或配置开关控制在开发环境可见不要裸奔到公网。4.4 调试时自动带token的正确姿势配置好SecurityScheme后点Swagger UI右上角的Authorize输入Bearer 实际token之后所有接口请求都会自动带上Authorization: Bearer ...头。有一点得留意bearerFormat(JWT)只是给UI做展示它不会真的校验你的token格式。如果你用的是OAuth2 client credentials也可以用SecurityScheme.Type.OAUTH2那要看SpringDoc的OAuth2配置段落比JWT复杂不少。我们在内部环境里还做过一个小优化开发环境自动创建一个测试用户Swagger UI打开时默认从后端的Mock接口拿一个有效token填进去这样前端联调时连登录步骤都省了。这个思路不一定要学但能明显减少“文档能看不能调”的时间。5. 把第三方HTTP接口云MAS平台短信也纳入文档体系SpringDoc扫描的是自己项目里的Controller对外部接口它无能为力。但我们在实际项目中对接了大量第三方HTTP接口最典型的就是各种短信网关。比如我接过的云MAS平台官方提供的HTTP接口文档还是传统的Word/PDF参数说明和签名规则分散在多个文件里前端、后端、测试各存一份经常对不上。5.1 外部接口文档到底乱在哪第三方接口文档常见三宗罪第一签名算法描述不清比如MD5还是HMAC-SHA256大小写转换规则不写第二响应码表不全很多平台只给你成功场景的JSON失败返回全靠试第三字段可空性乱标文档写“手机号必填”实际调用时又要求带区号临时找客服才问到。这些坑靠人传人特别容易丢。我接手旧项目时经常看到对接短信的代码里写了一堆魔法数字旁边注释是“平台说这样传”。后来我决定把外部依赖也纳入自己的文档体系但不用SpringDoc硬扫。5.2 我的做法外部依赖说明Endpoint externalDocsSpringDoc的OpenAPI对象支持externalDocs这是一个可以挂链接和描述的地方。我把所有外部接口的完整说明整理成Markdown放在仓库的docs/external-api/目录下然后在SpringDoc的配置里把链接写进主页.info(new Info().description( 外部接口文档入口: [云MAS短信平台](https://docs.example.com/internal/sms-platform) )) .externalDocs(new ExternalDocumentation() .description(外部依赖统一说明) .url(https://docs.example.com/external-api/));同时项目里真正发短信的代码全部收敛到一个SmsClient里这个类内部写好JavaDoc和入参DTODTO字段上使用Schema(description 对应平台参数mobile)。这样虽然Swagger UI不会扫到SmsClient但它内部的字段描述会随着依赖打包进项目排查问题时能快速对齐。5.3 排障时的真实作用有一次生产环境批量发短信失败消息平台上显示“签名错误”。后端看日志发现我们的SmsClient已经把timestamp拼成了小写而平台要求大写因为我们在DTO字段描述里写清了“timestamp必须为大写字符串”前端按照文档传参后端按文档校验五分钟就定位到了不再靠翻聊天记录。如果当时只有一个对外暴露的Swagger页面第三方平台的签名细节根本没人看得见。这个思路的本质是SpringDoc不是万能的外接文档工具但它可以作为团队内部所有接口说明的聚合入口。内部接口用注解实时生成外部接口用在线文档链接挂载大家至少在同一个首页里找到所有需要的信息。6. 导出离线文档时“Excel损坏”的排查过程最近群里不止一个人遇到同一个问题从接口文档页面导出Excel拿回来双击Excel提示“文件格式和扩展名不匹配”甚至直接报损坏。这事儿在百度上一搜一大串但很多回答只告诉你“换个浏览器”“重新下载”没解决根因。6.1 先还原一下现场客户或测试需要一份离线接口清单于是有同事打开Knife4j或Swagger UI的导出功能选择导出Excel得到一个.xls文件。双击后Excel弹出警告点“是”能看到内容偶尔还出现乱码。如果是用WPS情况更怪有时能开但格式全错。6.2 排查链路第一眼看文件头这个故障最好不要在Excel里反复打开而是先看文件到底是不是真正的Excel。Linux和macOS直接执行file /tmp/api-docs.xlsWindows可以用Notepad或HxD打开文件看前几个字节。真正的.xls文件头应该以D0 CF 11 E0开头这是OLE2复合文档的固定魔数如果是504B0304那是xlsx如果你看到的是3C 21 44 4F 43 54 59 50很遗憾这其实是个HTML文件。6.3 损坏的根因导出功能名不副实排查到最后大多数“Swagger导出Excel损坏”的由来是离线导出组件没有真的生成Excel二进制文件而是生成了一张HTML表格然后强制把扩展名写成.xls。Excel为了兼容老网页导出的HTML表格通常会弹一个“格式不匹配”的警告。如果HTML里的表格结构不完整或者包含大量带转义的JSON示例Excel解析时就会直接判定文件损坏。还有一类情况是Knife4j的导出依赖POI。如果项目里已经引入了其他版本的POI或者二进制库被Shading打包搞坏导出线程运行时报错前端拿到的是部分生成的半截文件。这种你会在浏览器Network面板里看到导出接口返回了500或者响应Content-Length异常。6.4 离线文档的稳定导出路线我自己已经不指望页面上的导出Excel按钮了。稳定做法是先拿到OpenAPI JSON再按需转换访问/v3/api-docs把JSON保存为openapi.json。需要YAML时访问/v3/api-docs.yaml。需要给客户看完整页面时用Redoc或Swagger UI的静态托管生成离线的HTML单文件。确实需要Excel时用脚本解析openapi.json自己生成一份干净的表格不要依赖导出插件。下面这个Python小脚本可以快速把path和method整理成CSVimport json import csv with open(openapi.json, r, encodingutf-8) as f: data json.load(f) rows [] for path, methods in data[paths].items(): for method, op in methods.items(): rows.append([ method.upper(), path, op.get(summary, ), op.get(operationId, ) ]) with open(api-list.csv, w, newline, encodingutf-8-sig) as f: writer csv.writer(f) writer.writerow([Method, Path, Summary, OperationId]) writer.writerows(rows)这样生成的CSV可以用Excel直接打开再另存为xlsx不会出现任何“损坏”警告。如果你必须用Knife4j导出建议给文档组单独准备一个环境避免POI依赖和生产项目相互污染。7. SpringDoc还能再往前一步把文档变成回归测试的一部分集成SpringDoc之后文档和代码是同源的这一步已经赢了大多数手写Word的项目。但文档和实现仍然可能“悄悄漂移”比如你重构了RequestParam的名字代码没编译错Swagger页面上的参数却变了对讲方还拿着旧文档调半天。要让文档不骗人最好把文档也纳入自动化检查。7.1 把OpenAPI JSON当契约文件纳入版本管理现在很多团队都是启动项目才生成文档没有一份可以审阅的静态契约。我建议每次版本发布前导出一份openapi.json提交到Git。这样代码review的时候文档变更也是diff的一部分。前端对接一版接口可以直接基于这份JSON生成TypeScript客户端减少同步成本。7.2 用openapi-diff查破坏性变更社区里有现成的openapi-diff工具可以比较两份OpenAPI JSON之间所有兼容性变化。比如“把一个必填参数改成可选”是向后兼容的而“删除一个接口”“改参数名”“把必填参数删掉”是破坏性的。把它接入CIopenapi-diff old-openapi.json new-openapi.json --fail-on-incompatibleCI失败团队负责人就会去找是谁改了接口没通知下游。这比“你说你改了但前端没看到”要好太多。7.3 在集成测试里校验文档基本健康度我自己在项目里跑的一套基础校验就是三个断言Test void swaggerDocsShouldBeHealthy() throws Exception { mockMvc.perform(get(/v3/api-docs)) .andExpect(status().isOk()) .andExpect(jsonPath($.openapi).exists()) .andExpect(jsonPath($.paths).isNotEmpty()); }别小看这个测试它至少能拦住“接口文档挂掉”“路径被Security拦截”“SpringDoc配置被覆盖”这类低级问题。再进一步可以断言每个operationId唯一、每个路径都有至少一个response。这些用一个小脚本就能扫出来规则不要定太多否则后续维护会变成负担。7.4 不要为了自动化把文档写成天书自动化校验解决的是“文档和代码不一致”但解决不了“描述写得太烂”。我的经验是文档注释应该控制在“接口做什么、参数边界、错误码含义”三个粒度。不要每一个getter都写一段长篇说明那只会让重要信息沉没。把时间花在哪几个字段上就是那些让前端反复问你的字段格式、枚举值、可空性、长度限制。最后分享一个我坚持了很久的习惯我踩过太多文档坑之后养成了一个习惯每次上线前都手动看一眼/v3/api-docs.yaml从第一行滚到资源列表确认没有莫名其妙多出来的端点也没有被隐藏掉的异常状态。然后再跑一次openapi-diff把破坏性变更在测试环境就拦住。SpringDoc本身不是什么神奇框架它只是把“接口文档”从一个静态交付物变成了和代码绑定的活物真正让它值钱的是你愿不愿意像维护代码一样去维护文档。如果你是第一次在一个老项目里接它记得先备份当前Swagger页面截图后面再也不用为文档吵嘴架了。
