我用 AI 把接口文档从 3 小时压到 20 分钟,完整步骤在这里

写接口文档这件事，我以前特别不想干。

不是不会，是觉得投入产出不成比例——花两三个小时一个字一个字敲，写出来的东西好像也没人仔细看。

后来我摸出了一套 AI 配合的流程，彻底改变了这件事的体验。

现在一个中等复杂度模块（5-8 个接口），20 分钟出初稿，10 分钟自己核一遍，质量比以前手敲的还稳。

把这套流程拆开讲。

把接口方法的代码贴给 AI，附一句明确的格式要求：

“这是我的接口代码。请按以下格式生成文档：接口名称、请求方式、请求路径、请求参数（含字段名、类型、是否必填、说明）、返回字段（含字段名、类型、说明）、正常响应示例、错误码说明。”

AI 能从代码里直接推断出参数名、类型、大致用途，给你一份八九成完整的骨架。

这一步通常 3 分钟搞定，省掉的是最机械的部分。

AI 能看出 status 是个 int 字段，但它不知道 1=启用、2=禁用、3=待审核。

枚举值、业务规则、特殊逻辑——这些只有你知道。

告诉它：

“以下是这个接口涉及的枚举值和业务规则，帮我把文档里对应字段的说明补充完整。”

然后把枚举类或产品文档的相关内容贴过去。

这一步 3-5 分钟，但文档的可读性会从”勉强能用”升到”前端拿来就能联调”。

文档里最花时间的，往往是手工拼 JSON。

直接让 AI 生成：

“基于以上文档，帮我生成一组完整的请求示例和正常响应示例。字段值用合理的模拟数据，不要用 xxx 或 string 占位。”

它生成的示例通常比手工拼的更完整，不会漏字段，而且数据看起来更像真实场景。

最后一步是换视角。

“你是一个前端开发，拿到这份接口文档准备联调。你会有哪些疑问？哪些字段说明不清楚？哪些地方容易产生误解？”

这一步的价值在于：你作为文档作者，已经对接口太熟了，很多在你眼里”显然”的东西，调用方看来并不显然。

让 AI 当一次”第一次看文档的前端”，往往能揪出你不自觉跳过的关键说明。

一个 5-8 个接口的模块，过去手写要 2-3 小时。

现在整个流程走下来，30-40 分钟搞定，文档质量反而更稳——因为每一份都经过了自检。

省出来的时间，可以做更有价值的事。或者早点回家。

#程序员最该先让 AI 帮你省掉的，不是写代码而是写文档 

#接口文档里最容易漏的几个字段说明，少写一个就多联调半天 

#用 AI 做文档自查，比自己二次阅读更容易发现盲区 

#周报、复盘、接口文档，哪类文字工作最适合先交给 AI 

#普通程序员怎么把 AI 文档生成接进日常工作节奏