上周组里新来的实习生小张，花了三天写完一个用户登录接口，结果被组长叫去改了七遍文档——字段名大小写、参数是否必填、返回示例格式，全得手动对齐。最后他蹲在工位上一边敲 Markdown 一边嘀咕：‘这哪是写接口，这是抄经啊。’
别再手写接口文档了
真实情况是：后端刚改完一行代码，Swagger UI 上的响应字段就自动变了；前端打开 Postman 点两下，就能看到最新请求结构；测试同学直接导出 PDF 去跑用例——这些都不是幻想，靠的是接口文档自动生成工具。
它们不造轮子，只盯代码里的注释和结构。比如 Spring Boot 项目里加个 @ApiOperation 注解，或 FastAPI 里写个 docstring，工具扫一遍，HTML 页面、Markdown 文件、甚至 Confluence 页面就齐活了。
几个真正在用的工具
Swagger UI（OpenAPI）：老牌但没过时。配合 springdoc-openapi，启动服务后访问 /swagger-ui.html 就能看到实时界面，支持在线调试。
@Operation(summary = "获取用户信息")
@GetMapping("/users/{id}")
public User getUser(@Parameter(description = "用户ID", required = true) @PathVariable Long id) { ... }Apifox：国内团队用得多。能从代码扫描、也能从接口测试反向生成文档，还带 mock 数据和自动化测试，UI 比 Swagger 友好不少，连产品经理都愿意点开看。
Stoplight Studio：适合想先定契约再开发的团队。用 YAML 写 OpenAPI 规范，保存即渲染，改完规范，前后端各取所需——前端拿 mock，后端生成 SDK，文档同步更新。
为什么它比你手写靠谱？
手写文档最大的问题是‘一动全废’：字段删了，文档忘了删；类型从 string 改成 int，示例还是 '123'；更别说多人协作时，A 改了代码没改文档，B 按旧文档联调，卡半天才发现是字段名多了个下划线。
而自动生成工具把文档和代码绑死。改代码 → 注释/注解跟着改 → 文档立刻刷新。不是省时间，是断了‘文档滞后’这个毒瘤的根。
某电商后台团队上线这套流程后，接口联调平均耗时从 1.5 天降到 4 小时，测试同学说：‘终于不用截图问后端这个字段到底允不允许为空了。’