用 AI 写接口文档：怎么让文档可维护

接口文档的问题从来不是写不出来，而是写完就开始过期：半年后参数对不上、错误码变了、示例跑不通。用 AI 写文档解决的是「写得快」；能不能「活得久」，取决于文档结构本身，以及文档和代码有没有绑在一起变更。这篇从一份可维护文档的五块内容讲起，给出让 AI 按框架生成、防止分叉的具体做法。

一份能用得久的文档包含哪五块

五块内容缺一不可：用途一句话，说清这个接口解决什么问题、什么场景该用它；请求与响应，字段名、类型、是否必填、取值范围逐项列全；错误码，每个码对应的原因和处理建议；可运行示例，能直接复制跑通；边界说明，限流、超时、幂等性、并发限制。前四块多数团队都写，第五块最常被漏，而调用方踩坑恰恰多踩在边界上。

边界说明是最容易欠债的部分

限流不写清，调用方高峰期拿到一串失败请求却不知道原因；超时不写，对端只能靠猜；幂等性不说明，重复提交可能演变成重复扣款类事故。写边界有个固定清单：触发条件是什么、超过之后返回什么错误码、调用方该怎么处理，三项齐了才算写完。文档里每省一条边界说明，都是给将来埋一笔债。

让 AI 按固定框架生成初稿

把接口定义或实现粘给 AI，要求按固定框架输出：用途、请求参数、响应字段、错误码、示例，一项不落；再让它给三个典型调用示例。提示词里必须写两条约束：一是只依据提供的内容，不编造字段——AI 补出来的字段看着合理，接不上就是事故；二是主动列出含糊之处，参数说明里「调用方容易误解的地方」让它自己挑出来。

生成之后有一步人工活省不得：把必填和可选逐项核对，说明不传时的默认行为。这一步 AI 替代不了，它不知道服务端对缺省值实际怎么处理。

文档为什么一定会过期

根因是文档和代码分属两处、各自变更。只要它们能被分别更新，分叉只是时间问题。可行的绑定有两种：接口定义由代码生成，文档跟着代码走；至少做到两者在同一提交流程里变更，改接口的提交不同步改文档，就合并不进去。靠自觉更新文档，从来靠不住。

四类字段的写法对照

版本变更怎么管

破坏性变更提前公告，给调用方至少两周的迁移期，让人有时间改代码；文档版本和接口版本对齐，避免看着新文档调老接口。每个版本留变更记录，按新增、废弃、行为变更三类列，调用方升级时扫一眼就知道要动哪里。

它做不到什么

AI 不知道你的服务端实际行为：缺省值怎么处理、限流阈值是多少、哪个错误码在什么条件下返回，这些只存在于代码和运维配置里，从定义文本推不出全部。它生成的示例格式正确，能不能跑通必须实际调用一次验证。把 AI 定位成初稿工具，核对与验证两步人工来做，这个分工不能反。

接口文档速查

• 五块内容：用途、参数、错误码、示例、边界说明
• 边界固定三项：触发条件、返回错误码、处理建议
• 提示词两条铁律：只依据给定内容、主动列出含糊处
• 文档与代码同一提交流程变更，防分叉
• 版本对齐，破坏性变更至少提前两周公告

文档维护的三个新问题

• 老接口没有文档，能让 AI 从代码反推吗？：可以当起点，但反推只覆盖代码字面行为，缺省处理、隐藏限流这类藏在配置里的信息推不出来，逐项人工确认后才能对外。
• 内部接口和开放接口的文档标准一样吗？：不一样。开放接口的示例和错误码要求更严，调用方没有渠道问你；内部接口可以省示例，边界说明不能省。
• 文档用中文还是英文写？：跟着主要调用方走。出双语版本时先定哪份是权威版本，另一份明确标注以哪份为准，否则两份各改各的又是一处分叉。

「只依据给定信息」是用 AI 写东西的通用纪律，用 AI 写商品标题时对平台规则的约束是同一个道理；把一段话压成一句卖点的能力，主图卖点的一句文案方法可以直接迁移到接口用途那一行；文档的定期核对别凭热情，年度复盘的数据总结法里的固定节奏拿来就能用。