去年秋天帮一个做电商的信息泄露朋友看服务器日志，发现有人用脚本在凌晨三点批量请求 /swagger-ui.html，漏洞十分钟内扫了四百多个路径。信息泄露他当时还觉得奇怪，漏洞说这破页面有什么好扫的信息泄露。我让他打开那个地址，漏洞浏览器里直接蹦出一份完整的信息泄露 API 文档，从用户登录、漏洞订单查询到后台管理接口，信息泄露参数格式、漏洞鉴权方式、信息泄露甚至内部测试用的漏洞 debug 接口全列在上面。攻击者连逆向的信息泄露功夫都省了。

Swagger 本身是漏洞个好东西。前后端分离之后，信息泄露接口文档靠手写根本跟不上迭代速度，Swagger 能自动生成可交互的 API 说明页面，开发调试效率翻倍。问题出在部署习惯上——很多团队把 Swagger UI 和业务接口打包在同一个应用里，生产环境直接对外暴露，既没加访问控制，也没做路径隔离。这等于把自家门锁的构造图贴在防盗门上。

泄露的内容比大多数人想的要命。/v2/api-docs 或 /v3/api-docs 返回的 JSON 里，每个接口的路径、HTTP 方法、请求参数名、数据类型、是否必填、甚至示例值都写得清清楚楚。有些团队用 Springfox 或 SpringDoc 时没关掉 @ApiOperation 的 notes 字段，结果内部备注也一并输出，比如“此接口未做权限校验，仅限内网调用”。攻击者拿到这份清单，等于有了精确的靶子：哪些接口需要 token，哪些不需要；哪个参数可能存在 SQL 注入，哪个文件上传接口没限制后缀。去年某物流公司的数据泄露事件，起因就是 Swagger 文档里暴露了一个 /internal/export 接口，参数直接传数据库表名，连注入都省了。

更隐蔽的风险在于版本差异。开发环境用的 Swagger 配置可能和生产不一样，但有些团队图省事，把 springfox.documentation.enabled 设成 true 就上线了。我见过一个案例，生产环境的 Swagger 文档里多出一个 /actuator/env 的接口映射，虽然实际路径被 Spring Security 拦了，但文档暴露了 actuator 端点确实存在。攻击者顺着这个线索去试 /actuator/heapdump，最后真把内存里的数据库密码捞出来了。

怎么防？最直接的办法是生产环境彻底关掉 Swagger。SpringBoot 项目里加一行 springdoc.api-docs.enabled=false 或者 springfox.documentation.enabled=false，重启完事。但有些团队需要给内部前端同事看文档，那就得做访问控制。Nginx 层加个 allow 10.0.0.0/8; deny all; 是最低成本的方案，或者用 Spring Security 给 /swagger-ui/** 和 /v3/api-docs/** 单独配个角色。别用 basic auth 糊弄，那玩意儿在 HTTP 明文传输里跟没加一样。

还有一种情况是网关层做了路由转发，Swagger 路径被漏掉了。比如网关只拦了 /api/**，但 Swagger 的静态资源路径是 /swagger-ui/，结果直接绕过去了。这种得在网关配置里显式把 Swagger 相关路径加到黑名单，或者干脆在网关层统一做鉴权，别指望后端每个服务自己管。

我自己的习惯是，每次渗透测试或者帮人看配置，先跑一遍 dirsearch 扫 Swagger 常见路径。命中率不低，尤其是那些用 JeecgBoot、RuoYi 这类开源脚手架的项目，默认配置里 Swagger 就是开着的。有些开发者觉得“我文档里没写敏感接口”，但自动生成的文档会把所有 @RequestMapping 的方法都列出来，包括那些忘了加 @ApiIgnore 的内部方法。一个 /test/sendMail 接口，参数是收件人和内容，攻击者拿它当免费邮件服务器发钓鱼信，这种事出过不止一次。

说到底，Swagger 泄露不是漏洞，是配置疏忽。但它带来的信息优势太明显了，攻击者从“盲打”变成“看着答案做题”。你不需要把 Swagger 当成洪水猛兽，但至少别让它出现在公网 IP 的 80 端口上。花五分钟改个配置，比事后查日志追攻击者轻松得多。