用 AI 写 API 文档：别只列字段，要让调用者能处理失败、权限和版本变化

团队让 AI 给一个新接口写文档。几分钟后，它产出了一张漂亮的字段表，却没说访问令牌放在哪里、重复请求会不会创建两笔订单、超时后能不能重试，也没告诉调用方错误码 409 到底该怎么处理。文档看起来完整，第一次接入还是要靠猜。

API 文档不是代码的散文版，而是服务提供方和调用方共同遵守的契约。AI 很适合整理结构、补示例和寻找缺口，但前提是让它依据真实规范工作，并把无法验证的内容明确标出来。

好文档要帮助调用者完成任务

调用者通常按“找到入口、获得权限、发出请求、理解结果、处理失败、稳定上线”的顺序阅读。只按控制器文件逐个解释函数，会把实现结构强加给读者。先写用户要完成的场景，再链接到具体接口和数据模型。

先确定唯一可信来源

OpenAPI 文件、代码注解、网关配置和手写文档如果都能单独修改，很快就会互相矛盾。团队应明确哪一份是源头，其他内容由它生成或通过测试校验。AI 的输入也必须来自这个源头及已确认的业务说明，而不是从过期 Wiki 拼出一个看似合理的版本。

给 AI 足够上下文，但不要交出秘密

输入可包括接口规范、认证方式、错误目录、状态机、版本策略和脱敏示例。不要粘贴生产令牌、私钥、真实客户数据或内部未授权源码。使用组织批准的模型环境，并记录哪些文档由 AI 辅助生成、由谁审核。

环境和基础地址必须明确

说明生产、沙箱和本地环境的 Base URL，各环境数据是否隔离、凭证是否通用、沙箱会不会真实扣款或发送消息。示例命令应完整到可以执行，但令牌使用占位符，并提醒调用者不要把凭证提交到仓库或前端代码。

认证不只是一行 Header

写清令牌如何申请、作用域代表什么、何时过期、如何轮换，以及缺少权限和身份失效分别返回什么。若签名依赖时间戳、nonce 或请求体摘要，应给出规范化步骤和时钟偏差要求。AI 可以生成伪代码，但必须用官方 SDK 或测试向量验证。

字段要区分缺省、空值和默认值

“可选”不等于“随便不传”。字段未出现、显式传 null、空字符串和零可能代表四种行为。每个字段说明类型、是否必填、取值范围、格式、单位、默认逻辑、条件约束和敏感性。枚举还要告诉调用者遇到未来未知值时怎么办。

响应示例要覆盖失败

只有 200 示例会让调用方在真实故障时手足无措。至少覆盖认证失败、权限不足、参数错误、资源不存在、状态冲突、限流和服务异常。错误响应应有稳定机器码、可读信息、请求追踪号，并说明哪些错误可以重试、哪些需要修改请求。

一个实用判断：如果调用者只能通过阅读服务端源码判断是否重试，API 文档就还没有完成。

幂等和重试必须一起写

网络超时并不说明服务端没有成功。对创建订单、付款和发券等操作，说明是否支持幂等键、键的作用范围、保留多久、相同键但参数不同会怎样。给出退避、抖动和最大重试次数，禁止用“失败就重试”掩盖重复副作用。

分页规则决定数据会不会漏

写清游标或页码如何使用、排序是否稳定、页大小上限和结束条件。数据在翻页期间变化时，新增、删除或更新会不会造成重复和遗漏，也应说明。示例要展示如何循环到最后一页，而不只是第一屏。

限流不是只写一个数字

除了每分钟请求数，还要说明按账号、令牌、IP 还是接口计数，响应头如何显示剩余额度，窗口何时重置，超过后返回什么。若批量接口、异步任务或 Webhook 能降低轮询压力，应在高频场景中主动推荐。

异步任务与 Webhook 要写状态机

提交成功不等于处理完成。列出 pending、running、succeeded、failed、canceled 等状态，说明查询频率、最终结果、失败原因和保留时间。Webhook 需说明签名验证、重放保护、重复投递、顺序不保证以及接收端应如何快速确认。

示例代码必须能被自动执行

AI 很容易生成字段名正确却无法运行的 SDK 调用。把文档中的 curl、JavaScript 或 Python 示例提取到测试环境执行，校验状态码、Schema 和关键字段。示例失败应阻断文档发布，这比人工浏览更能防止版本漂移。

版本变化要告诉调用者怎么迁

区分新增可选字段、行为调整和破坏性变化。写清弃用起点、替代接口、兼容窗口、最后支持日期和迁移前后示例。不要静默改变默认值或错误语义；即使 Schema 没变，排序、精度和状态转换改变也可能破坏调用方。

让 AI 做差异审查

把上一个已发布规范与当前规范同时提供给 AI，让它按新增、删除、类型、必填性、枚举、默认值、状态码和行为说明生成变更候选。随后由契约测试与负责人确认。AI 没看到的运行配置、网关规则和灰度逻辑仍要人工补充。

推荐的写作流程

1. 确认 API 的用户、任务和唯一可信规范。
2. 生成端点、模型、认证、错误与状态的覆盖清单。
3. 先写快速开始和完整业务流程，再补接口参考。
4. 让 AI 标记矛盾、空缺与无法确认项，不准擅自补全。
5. 在沙箱执行所有示例与契约测试。
6. 由开发、安全、支持和真实调用者共同评审。
7. 随发布自动检查差异并更新变更记录。

可直接使用的提示词

“你是 API 技术写作助手。只能依据编号 OpenAPI、认证规范、错误目录、状态机和版本政策。先按调用者任务建立文档目录，再列出矛盾、缺失信息和待确认问题。每个接口写用途、前置条件、认证、请求字段、成功响应、错误语义、幂等、重试、限流和可执行示例。严格区分未传、null、空值和默认值；禁止虚构字段、SDK 或状态码。最后给出需要契约测试验证的清单。”

发布前检查清单

• 新调用者能否只按快速开始成功请求一次？
• 文档与代码是否有明确的单一可信来源？
• 权限、空值、错误、重试和幂等是否说清？
• 分页、限流、异步任务与 Webhook 是否可操作？
• 示例是否在当前版本沙箱真实运行？
• 破坏性变化是否给出期限和迁移步骤？
• 文档中是否没有真实凭证和敏感数据？

AI 能让文档更快成形，但不能决定未写下的接口承诺。真正可靠的 API 文档来自同一份规范、可执行示例和持续契约测试：它不仅告诉调用者“怎么成功”，也告诉他们出错、变化和恢复时该怎么办。

本文为读懂 AI 原创内容。处理内部接口、源码、凭证与客户数据时，请遵守组织的访问控制、保密和安全政策；AI 生成的字段、代码和行为说明必须由系统负责人验证。