swagger避坑：别只会加注解
swagger避坑的关键，是先理解它为什么会“看起来自动、实际很脆”。它从代码、注解或配置里抽取接口元数据，再渲染成文档页面。只要源头混乱，页面就会混乱。下面拆开讲几个底层逻辑和项目里最常见的坑。
Swagger 的本质：接口元数据搬运工
Swagger 并不会读懂你的业务，它只是把接口路径、HTTP 方法、参数类型、响应模型、描述文字收集起来，整理成 OpenAPI JSON，再交给 UI 展示。也就是说，它生成的不是“正确文档”，而是“你暴露给它的信息”。
这点特别重要。很多人看到页面能打开，就以为文档好了。其实接口里的 Integer 是金额还是数量、status 的 1/2/3 分别代表什么、分页从 0 还是 1 开始，Swagger 都不会凭空知道。没写就没有，乱写就乱展示。
坑一：接口返回统一包装，结果文档全变套娃
Java 项目里常见 Result<T>、ResponseVO<T> 这种统一返回。如果泛型解析没处理好，页面上只看到 code、message、data，却看不到 data 里面的真实字段。前端打开一看：这不等于没写吗？
解决思路不是把统一返回删了，而是确认你用的 Springdoc、Knife4j 或旧版 Springfox 对泛型支持是否正常。复杂响应最好加具体 schema 示例。对列表、分页、嵌套对象尤其要补 example，不然联调时一定会反复问。
坑二：把生产环境文档直接暴露出去
Swagger 页面在内网很方便，在公网就是攻击者的菜单。接口路径、参数名、管理端入口、上传接口、调试按钮，全都摆在页面上。以前见过项目把 /swagger-ui.html 放线上，连测试 token 示例都没删，离谱但真常见。
上线策略要硬一点：生产环境关闭 Swagger UI，或至少加网关白名单、登录权限、IP 限制。OpenAPI JSON 地址也别忘了拦，很多人只关页面，/v3/api-docs 还裸奔。安全不是吓唬人，这个坑成本很低，但后果很烦。
坑三：版本升级随手改，依赖直接打架
Spring Boot 2 和 3 的 Swagger 生态差别不小。老项目常用 Springfox，新项目更多用 springdoc-openapi。Boot 3 切到 Jakarta 包名后，旧依赖经常启动就报错。别在周五下午升级，不然你会和 ClassNotFoundException 对视一晚上。
稳妥做法是先看框架版本矩阵：Spring Boot 2.x 配 springdoc 1.x 较常见，Spring Boot 3.x 通常配 springdoc 2.x。迁移前拉个最小 demo 验证启动、分组、鉴权、文件上传、泛型返回，再动主项目。
回到一句话：Swagger 要管源头
swagger避坑不是背注解大全，而是管住信息源、访问权限和版本兼容。接口描述从代码来，就把注解规范写进 review；从 YAML 来，就把 OpenAPI 文件进 Git；要开放页面，就确认环境隔离。
真正好用的 Swagger 文档有三个特征：字段解释像人话，示例数据能直接复制，接口变更有记录。做到这三点，前端少骂两句，测试少抓两个群，后端也不用天天当人工文档。
常见问题
Swagger 线上环境要不要关闭？
建议关闭 UI 页面和 API docs 地址。确实要保留时，至少加登录、IP 白名单或网关鉴权。
Spring Boot 3 用哪个 Swagger 依赖？
通常选 springdoc-openapi 2.x 系列，旧 Springfox 在 Boot 3/Jakarta 环境里兼容性问题较多。
Swagger 文档字段不显示怎么办？
先检查实体类 getter、注解位置、泛型返回解析、是否被忽略注解过滤，再看依赖版本是否支持当前框架。