编写API文档这件事，说真的，大概是程序员最不想碰的活儿了。代码写完了，功能跑通了，一说到补文档，大家就开始各种拖延。文档过期、格式乱、参数写得含糊不清，这些问题基本每个团队都躲不掉。我自己就栽过跟头，有一回文档跟代码完全对不上，前端同事追着我问接口字段，最后我花了一整个下午重新整理才搞定。后来我开始用AI助手来生成和更新API文档，发现只要方法对了，这事儿能轻松不少，文档质量和代码同步率也提高了。下面这几个技巧，都是我踩过坑之后总结出来的，希望能帮你少走点弯路。
第一个技巧，先让AI了解项目背景，别上来就让它写文档。很多人打开AI工具就直接说“帮我写这个接口的文档”，然后贴一段代码过去。结果往往不太理想，因为AI根本不了解你的项目背景、命名习惯、错误处理方式，生成的文档看着挺全，其实很多细节都是它自己猜的。我的做法是，先给AI一个项目概览，包括目录结构、主要模块职责、常用的响应格式和错误码约定。你可以把这些信息整理成一个文件，然后告诉AI，这是项目背景，请先读一下，之后我会给你具体接口代码，你基于这个背景来生成文档。这样AI生成的文档就能贴合项目风格，不会写得太泛。
第二个技巧，用AI自动提取接口参数。传统写文档的方式，得人工去读代码，手动列出参数、类型、必填项和默认值。这个过程很费时间，还容易漏，尤其是接口参数多或者有嵌套对象的时候。AI可以帮你做这一步，你把接口的完整代码，包括Controller层、Service层和DTO定义都给它，让它提取所有字段，并标注类型、是否必填、默认值。在提示词里明确说，请分析这份代码，列出所有请求参数和响应字段，包括嵌套对象，注明类型和约束。AI通常会给出一个结构化的列表，你再人工核对一遍，效率比从零开始高多了。关键是要把完整代码给它，不能只给方法签名，因为参数校验逻辑往往在方法体里，只有看到完整实现，AI才能准确判断字段是不是必填的。
第三个技巧，用AI做变更检测，保持文档同步。文档同步最大的难点，就是代码更新了，文档忘了改。AI能解决这个问题，但前提是给它一个对比的任务。比如你改了一个接口，把某个字段从可选改成必填，或者加了新的错误码。你把修改前后的代码都给AI，告诉它，这是修改前的代码，这是修改后的代码，请找出差异，并更新对应文档段落。AI会指出变更点，并生成更新后的文档片段。如果你用Git管理代码，可以定期把最近一次提交的diff内容复制给AI，让它检查现有文档是否需要更新。这样你就不用每次手动比对代码和文档了，AI帮你完成了最繁琐的检查工作。不过对AI的输出还是要保持审慎，因为它可能漏掉一些隐式变更，比如字段语义的变化。我的习惯是，让AI生成更新建议，然后我快速审查一遍，确认没问题再替换到文档里。
第四个技巧，让AI生成示例代码和错误场景。一份好的API文档，不只是列出参数和响应，还得有具体的调用示例和可能出现的错误情况。AI在这方面很擅长。你可以提供接口的完整定义，让它生成多种场景的调用示例，比如正常请求、带可选参数的请求、触发校验错误的请求。同时，让AI根据错误码约定，写出每个错误码的含义和排查建议。这样生成的文档对调用方很友好，能大大减少沟通成本。我之前让AI为一个登录接口生成五个错误场景示例，验证码错误、密码错误、账号锁定这些，前端同事看了之后直说专业。核心还是要提供足够的上下文，比如错误码规范和响应格式约定，这样AI生成的示例才能跟项目一致。
第五个技巧，建立定期同步机制，让AI辅助持续维护。一次性生成文档不难，难在持续维护。我的做法是每周花十分钟，整理本周改动的接口代码和相关文档段落，让AI做一次同步检查。可以给AI一个简单指令，请对比以下代码和对应文档，指出不一致之处，并给出修改建议。AI会生成一个差异清单，你按清单更新文档就行。如果你用的是支持API的AI工具，甚至可以写个脚本，在代码提交的时候自动触发AI检查，把结果发到群聊里提醒大家。虽然还没法完全自动化，但能省掉90%的人工比对时间。关键是养成习惯，把文档同步当成代码提交的一部分。坚持几周之后，你会发现文档过时的问题基本就消失了。
最后说一句，AI不是万能的，生成的文档有时候太啰嗦，有时候又会漏掉业务逻辑的说明。所以我的经验是，把AI当成一个高效的助手，而不是完全依赖它。你还是要清楚文档的读者是谁，是前端、测试还是第三方开发者，在AI生成的基础上，加上业务相关的注释和注意事项，这样文档才更有价值。另外，AI工具一直在进步，很多IDE插件已经能实时生成注释和文档了，建议多试试不同的工具，找到最适合你工作流的那一个。希望这些技巧能帮你从文档的苦海里解脱出来，把时间花在更有意思的编码上。
Top comments (0)