做后端的都懂，API文档这东西写起来烦，不写呢前端就得天天追着问。我之前带的项目就是这样，接口都快200个了，文档永远比代码慢一拍。上次前端的小伙伴跟我说某个接口参数不对，我一看——好家伙，三个月前就改了，文档根本没同步。
后来用TraeWork搞了一套自动化流程，简直是救命。
我是谁，我卡在哪
Java后端开发，干了快五年，目前负责一个中等体量的B端项目，接口大概200个左右。团队3个后端、4个前端、1个测试。
痛点很简单：API文档永远跟不上代码。我们项目用的Swagger注解，但大家写注解经常偷懒，参数描述随便写个"参数"就完事了，返回类型也经常不标。每次前端问"这个接口返回的xxx字段啥意思"，我都得去翻代码。更离谱的是有些接口改了参数，注解没同步，前端照着旧文档调，联调的时候才发现问题，一搞就是半天。
我之前试过手动维护一份Markdown文档，根本坚持不下来。代码改一处文档就得跟着改，谁有那个耐心。
我用 TraeWork 怎么解决的
使用模式：Code 模式
整个过程分三步：扫描代码 → 生成文档 → 定时同步。
第一步：写扫描脚本提取接口定义
用TraeWork的Code模式写了个Python脚本，扫描项目里所有Controller文件，提取Swagger注解里的接口信息（路径、方法、参数、返回类型），输出成结构化JSON。
跟TraeWork对话的时候，我直接把Controller的代码片段丢给它，告诉它我要提取哪些注解信息。第一版生成的脚本基本能跑，但有些接口的注解写法不太规范，比如有的用@ApiParam有的用@Parameter，得加容错处理。来回调了几次，每次把报错信息贴给它，它就能定位到问题然后改。
第二步：写Skill让AI生成Markdown文档
拿到JSON之后，又写了一个Skill，让AI根据每个接口的JSON定义自动生成Markdown格式的文档。包括接口名称、路径、请求方法、参数说明表格、响应示例、错误码说明这些。
Skill的prompt我调了好几次。一开始生成的文档太啰嗦，每个接口都带一大段说明。后来我告诉它只要表格+示例，不要废话，出来的效果就好多了。
第三步：配定时任务自动跑
用cron配了个定时任务，每天凌晨3点自动执行扫描脚本，生成最新文档，然后自动commit到一个独立的文档仓库。代码一变，第二天文档就自动更新了，完全不用人管。
提效前后对比
| 对比项 | 之前（手动维护） | 之后（自动生成） | 提效幅度 |
|---|---|---|---|
| 文档更新频率 | 想起来才更新，经常滞后2-3周 | 每天自动同步，最多延迟1天 | 从"按周滞后"到"按天同步" |
| 单个接口变更后的文档维护时间 | 10-20分钟/个接口 | 0分钟（全自动） | 节省100% |
| 文档格式统一性 | 每个人写的格式不一样，七零八落 | 统一模板，格式一致 | 从"各自发挥"到"完全统一" |
| 前端联调时因文档问题产生的沟通 | 每周3-5次来问接口细节 | 基本为0，文档就是最新的 | 减少约90% |
| 每月花在文档维护上的总时间 | 约15-20小时 | 约1小时（偶尔检查下生成质量） | 节省约95% |
| 新增接口的文档产出速度 | 写完代码还得单独花10-20分钟写文档 | 代码提交后第二天自动有文档 | 从"额外工作"到"零成本" |
简单说就是：以前每个月光维护文档就得花两三天，现在基本不用管了。最直观的感受是前端群里问接口问题的消息少了一大半，联调效率也上来了，以前一个迭代联调要两天，现在一天半就能搞定。
成果展示
产出物1：自动化API文档仓库
一个独立的Git仓库，按业务模块分目录存放Markdown文档。目录结构是这样的：
api-docs/
├── user/ # 用户模块
│ └── README.md
├── order/ # 订单模块
│ └── README.md
├── payment/ # 支付模块
│ └── README.md
└── README.md # 总目录索引
每个模块的文档里，每个接口一个section，包含：接口路径、请求方法、参数表格（参数名/类型/是否必填/描述）、响应示例JSON、常见错误码说明。前端同事直接打开这个仓库就能查到所有接口信息，不用再在群里挨个问。
产出物2：扫描脚本 + Skill
Python扫描脚本负责从代码提取接口定义，Skill负责把JSON转成可读的Markdown。两个东西配合就是完整的文档生成流水线。跑一次大概30秒，200个接口全扫一遍。
产出物3：定时任务配置
cron定时任务，每天凌晨3点自动跑，生成完自动commit到文档仓库。配置好之后就再也没手动管过，已经稳定运行了两个多月。
实践经验总结
-
Swagger注解质量是前提。如果你们项目的注解本身就写得乱七八糟，那生成出来的文档也没法看。建议先用TraeWork写个脚本批量检查一遍注解的完整性，把缺失的描述补上，再跑文档生成。我们项目第一遍扫出来有30多个接口参数描述是空的，花了半天补上之后效果好了很多。
-
Skill的prompt需要迭代。别指望一次就写出完美的prompt。我大概调了四五次，主要是在"详细程度"上做取舍——太详细了文档太长没人看，太简略了又不够用。最后发现参数表格+响应示例+常见错误码这个组合刚刚好。每次调整prompt之后跑一遍看看输出效果，不满意就继续改，直到生成的文档拿来就能用为止。
-
文档仓库和代码仓库分开。一开始我把文档放在代码仓库里，结果每次自动commit会触发CI，搞得同事老收到通知。单独建个文档仓库就清净了。这个坑踩了一天才发现，血泪教训。
-
容错处理很重要。真实项目里的注解不可能100%规范，扫描脚本一定要加try-catch，遇到解析不了的接口跳过并记录日志，别因为一个坏注解导致整个流程挂掉。我们项目就有几个老接口用了很奇葩的注解写法，第一版脚本直接报错退出了，加上容错之后才稳定下来。
分享你的实操对话
对话1：让TraeWork写扫描脚本
我： 帮我写个Python脚本，扫描Java项目里所有Controller文件，提取Swagger注解里的接口信息。需要提取的内容包括：接口路径（从@RequestMapping或@GetMapping/@PostMapping这些注解里取）、请求方法、参数列表（参数名、类型、是否必填、描述从@ApiParam或@Parameter里取）、返回类型。输出成JSON格式。这是我一个Controller的代码片段：[贴了UserController的代码]
TraeWork： [生成了第一版Python脚本，用正则匹配注解内容，支持了@GetMapping/@PostMapping/@RequestMapping，以及@ApiParam/@Parameter/@RequestParam/@RequestBody等常见注解]
我： 跑了一下大部分接口能解析，但有个问题——我们项目有些接口用了自定义的注解封装，比如@AuthUser这种参数注解，你的脚本没识别出来。这种也要处理，它的结构是这样的：[贴了自定义注解的代码]
TraeWork： [加了递归解析逻辑，遇到自定义注解会追溯到底层类型，同时把注解的元信息也提取出来]
这轮对话下来，扫描脚本基本就成型了。后面又跑了几次把报错信息贴给它修了几个边界case，比如有的接口没有注解只有注释，这些它都能处理。
对话2：调Skill的prompt控制文档格式
我： 我需要一个Skill，根据接口的JSON定义生成Markdown格式的API文档。JSON结构大概是这样：{“path”:“/api/user/list”,“method”:“POST”,“params”:[{“name”:“page”,“type”:“int”,“required”:true,“desc”:“页码”},{“name”:“size”,“type”:“int”,“required”:false,“desc”:“每页条数”}],“response”:{“code”:0,“data”:{“list”:[…],“total”:100}}}。帮我生成可读的Markdown文档。
TraeWork： [第一版生成的文档每个接口带一大段文字说明，包括接口功能描述、使用场景、注意事项等等，太啰嗦了]
我： 太啰嗦了，不需要那些文字说明。改成这样：参数用表格展示，只要参数名、类型、是否必填、描述四列。响应部分直接给一个JSON示例。再加上常见错误码就行。别的都不要。
TraeWork： [第二版改成了表格+JSON示例的格式，清爽了很多]
我： 差不多了，再调两个小地方：1. 表格里的"是否必填"列用"是/否"不要用"true/false"；2. 响应示例里的JSON帮我格式化一下，加上缩进，别挤在一行。
这轮对话的核心经验就是：给AI的指令越具体越好，别说"生成文档"这种模糊的话，要告诉它具体要什么格式、什么字段、什么结构。调了三四轮之后生成的文档基本拿来就能用了。
整个过程大概花了半天时间，主要时间都在调扫描脚本和处理不规范的注解上。TraeWork在写脚本和Skill这块确实省了不少事，不用我自己从头研究怎么解析AST。如果你们也有文档跟不上代码的烦恼，可以试试这个思路。