接口文档也能交给 AI 吗?我用 Codex + APIPost MCP 试了一次

以前我不太敢把接口文档交给 AI。

不是因为它写不了文字，而是接口文档这东西，看起来是文档，里面其实全是业务约定。

这个字段到底表示什么？老版本要不要兼容？返回结构里哪些是稳定承诺，哪些只是当前实现？这些地方如果让 AI 自己猜，文字可能很顺，真正联调的时候就容易出事。

最近做一次接口本地测试和接口文档更新，我试着把 Codex 和 APIPost MCP 接起来跑了一遍。

感受有点变化。

我发现，接口文档不是不能让 AI 帮忙，而是不能一上来就把判断权交给它。

这次的做法比较简单：先让 Codex 看项目上下文和已有文档，梳理这次涉及哪些接口；再配合 APIPost MCP 做本地测试和对照；然后让它列出文档里需要同步的地方。最后，我再逐项确认。

这个顺序很重要。

接口文档最烦人的地方，其实不是难，而是碎。

以前我很容易把这种活拖到最后做。代码已经改完了，接口也测过了，但文档还差一点。真到补文档的时候，又要重新回忆刚才改了什么、测了什么、哪些字段要说明。

你一会儿看代码，一会儿开接口工具，一会儿改文档，一会儿又回去确认字段含义。中间只要被消息打断几次，就很容易漏掉一个参数，或者把“当前实现”写成“接口约定”。

这次让 AI 参与后，它帮我省掉的不是判断，而是来回切换和整理。

它可以帮我把上下文读完整，把测试结果和文档结构对上，把可能需要更新的点列出来。至于这些点能不能写、怎么写、写到什么程度，还是我自己决定。

所以这件事和“让 AI 自动写一份接口文档”不太一样。

更准确地说，是把接口文档维护拆成了一套流程：

• • 先确认这次要测哪些接口；
• • 再让 AI 读取代码和已有文档；
• • 用接口工具对照请求和返回；
• • 生成一份待更新清单；
• • 最后人工验收。

以前这套流程主要靠记忆。现在它可以被写下来、跑起来，甚至继续沉淀成 Skill。

这点对我挺重要。

真实项目里的很多工作，并不是纯写代码。接口说明、测试记录、变更说明、上线检查、交付资料，这些东西平时不起眼，但一旦没跟上，后面联调和交付都会被拖住。

AI 如果只能帮我写代码，那它解决的是一部分问题。可如果它能把这些散落在工具和文档之间的动作串起来，价值就不一样了。

当然，边界也很明确。

我不会让 AI 自己决定接口应该怎么设计，也不会让它替我确认业务规则。尤其是企业系统、医疗系统，字段含义、兼容逻辑、数据口径都不能含糊。

AI 可以辅助整理，可以提醒遗漏，可以推进流程，但业务边界还是人来守。

这次流程跑通以后，我做的下一件事，就是让 Codex 把这个接口文档维护流程写成一份 Skill。

因为一次任务做快一点，只是省时间；把它沉淀成下次也能复用的步骤，才有点像自己的资产。

所以，接口文档能不能交给 AI？

我的答案是：能交一部分，但别把判断权交出去。

重复检查、上下文整理、文档同步清单，可以交给 AI；接口含义、业务边界和验收标准，还是要自己盯住。

我会持续记录一个普通程序员如何把 AI 工具真正接进工作流：真实案例、踩坑、复盘和可复用方法。如果你也在做这件事，可以关注我。

下一篇我准备接着写：这次 Codex + APIPost MCP 跑通以后，我是怎么把它沉淀成一份 Skill 的。