用 AI 编写 API 接口文档

昨天（Day 21）我们让风险学会了"自己报警"，第二阶段的项目层闭环完成。今天镜头切回单个交付物的精细度：API 接口文档。它有个特殊身份——系统之间的合同：前后端之间、微服务之间、你与外部供应商之间，靠的都是它。合同写糊了，扯皮就开始了。Day 17 详细设计里我们定过收货确认接口的幂等约定，今天就把"接口约定"升级成"接口合同"——用 AI 编写 API 接口文档。

先定验收标准，延续本周句式：接口文档的验收标准是"调用方拿着文档一次调通，全程不用抓着后端问字段；文档里每个字段都能在代码里找到出处，代码里每次变更都能反映进文档"。前半句考验完整性，后半句考验一致性——这恰好是接口文档的两大死穴。

一、先立观念：接口文档的三宗罪

接口文档的常见死法有三种，每种都见过无数次：

• 过期
  ——代码改了文档没改。过期文档比没有文档更危险：没有文档，调用方会来问你；过期文档，调用方会按错的调，然后怪你。文档一旦过期，就从资产变成了负债；
• 不完整
  ——只写正常场景，不写错误码、不写边界约束（字段长度、必填性）、不写幂等约定。调用方把能踩的坑全踩一遍；
• 格式不一
  ——每人一个写法，有人写 Word、有人贴截图、有人发口头消息。对接三个系统要读懂三种"方言"。

AI 在这里的价值是"翻译官 + 统一器"：把代码里的 Controller、DTO 翻译成结构化文档，把散落各处的约定统一成同一种格式。但要提前打一针预防：AI 会脑补——代码里没有的字段它可能帮你"合理想象"出来，约束没写的它可能默认宽松。所以接口文档的生成必须配"出处检查"，这个后面细说。

二、为什么选 OpenAPI：把接口写成数据，而不是散文

接口文档的载体选 OpenAPI（Swagger）规范，理由只有一个：它是机器可读的结构化数据。同样一份定义，写成 Word 只能给人看；写成 OpenAPI YAML，可以同时驱动 Mock 服务（前端不用等后端）、自动化接口测试、Swagger UI 在线调试、甚至客户端代码生成。一次编写，四处使用。

OpenAPI 的核心结构就四块，认识它们就够用了：

一句话记住：OpenAPI 把接口从"散文"变成"条款"——每个字段有类型、有约束、有出处，改没改、漏没漏，一眼可查。这也是它能被 AI 高质量处理的前提：结构化数据是 AI 最擅长校对的东西。

三、两条生成路径：从代码提炼 vs 从需求定义

接口文档有两种生成时机，对应两条路径。先分清再用：

下面用星辰 ERP 的三个业务接口走通两条路径：① 提交收货确认（幂等敏感）、② 收货单分页查询、③ 库存入库回执回调（库存服务 → 采购服务）。

四、路径一：让 AI 从 Controller 代码提炼文档

已上线的收货确认接口要补文档，把代码喂给 AI：

Prompt 模板 · 从代码生成 OpenAPI你是一位精通 OpenAPI 3.0 的接口文档工程师。请根据下面的代码，为"提交收货确认"接口生成 OpenAPI 3.0 YAML 片段：【要求】1. 完整覆盖：路径、HTTP 方法、路径参数、请求头、请求体、按状态码区分的响应2. 字段类型、必填性（required）、长度约束、枚举值必须严格从代码注解与 DTO 定义中提取，代码里没有的约束禁止编造；确实需要但代码没写的，单独列在"待人工确认"清单里3. 错误响应必须与全局异常处理器中的错误码体系一致，逐个列出业务错误码与触发条件4. 接口的幂等约定（如有幂等键请求头）必须在 description 中写清：幂等键从哪来、重复提交返回什么5. 鉴权方式在 securitySchemes 中声明，与项目现有网关鉴权一致6. 响应体统一使用项目的统一响应包装结构【Controller 代码】{{粘贴收货确认接口的 Controller 方法}}【DTO 定义】{{粘贴请求/响应 DTO 类（含校验注解）}}【全局异常处理器与错误码枚举】{{粘贴 Day 17 错误码表对应的枚举定义}}【统一响应结构】{{粘贴项目统一响应包装类}}

AI 提炼、人工校审后的 OpenAPI 片段长这样（节选主体）：

paths:  /api/v1/receipts/{receiptNo}/confirm:    post:      summary: 提交收货确认      description: >        对指定收货单执行确认收货，触发异步入库指令。        幂等接口：需携带 Idempotency-Key 请求头，        同一键重复提交返回首次结果，不重复触发入库。      security:        - bearerAuth: []      parameters:        - name: receiptNo          in: path          required: true          schema: { type: string, maxLength: 32 }        - name: Idempotency-Key          in: header          required: true          schema: { type: string, maxLength: 64 }          description: 幂等键，建议 UUID，同单据首次提交时生成      requestBody:        required: true        content:          application/json:            schema:              $ref: '#/components/schemas/ReceiptConfirmRequest'      responses:        '200':          description: 确认成功或业务拒绝（见 code 字段）          content:            application/json:              schema:                $ref: '#/components/schemas/UnifiedResponse'        '401': { description: 未认证或令牌过期 }

注意第 2 条要求的用意：AI 的产出里，"有出处的"和"待确认的"是分开的。校审时逐条对照 DTO 与 DDL：字段类型对不对、长度约束全不全、必填性准不准——凡是 AI"待人工确认"清单里的项，逐条拍板后回填进 YAML。

五、路径二：让 AI 从需求生成接口契约

库存入库回执回调是新接口，走契约先行：开发还没写，先把合同定下来。输入不是代码，而是 Day 17 详细设计里的接口约定：

Prompt 模板 · 从需求生成接口契约你是一位接口设计师。请根据下面的业务需求，设计"库存入库回执回调"接口并输出 OpenAPI 3.0 YAML + 设计说明：【要求】1. 定义：HTTP 方法、路径（回调类接口挂在 /callbacks 前缀下）、鉴权方式（服务间调用，与网关用户鉴权区分）2. 请求体覆盖回执的全部字段：回执单号、关联入库指令号、入库结果（成功/失败）、失败原因、回执时间；响应体约定采购服务的接收确认结构3. 幂等设计：网络重试可能导致同一回执到达多次，明确幂等键与重复回执的处理约定4. 错误场景完整：回执单号不存在、指令号不匹配、重复回执、报文格式错误，各自返回什么错误码5. 时序异常说明：回执先于本地状态落库到达时如何处理（引用详细设计边界清单的约定）6. 设计说明单独成节：解释每个决策的依据，与现有接口风格保持一致之处要显式说明【业务需求】{{粘贴 PRD 中回执相关验收条款}}【详细设计接口约定】{{粘贴 Day 17 回执处理的状态机、错误码表、边界清单}}【现有接口风格样例】{{粘贴第四步生成的收货确认 OpenAPI 片段}}

这里有个文档链细节：最后一段"现有接口风格样例"就是把上一份产出当输入——AI 对齐的是你项目自己的合同模板，而不是它训练数据里某个陌生项目的风格。契约生成后丢进评审会，前端拿去配 Mock，后端照契约开发，两边从此不用口头对齐。

六、示例与错误码：让文档"可试"而不是"可读"

有了结构定义，还差两样东西才算完整合同：请求/响应示例（正常 + 错误场景各配 JSON，调用方能照着试）和全局错误码表（所有接口共用一套语言）。一个 Prompt 一起生成：

Prompt 模板 · 示例、错误码与变更记录请为下面的接口补齐三样内容：一、请求/响应示例：每个接口生成正常场景与典型错误场景的示例 JSON——正常场景给完整业务数据；错误场景至少覆盖：业务规则拒绝（引用错误码表）、参数校验失败、鉴权失败，各配一段真实结构的 JSON 与触发条件说明二、全局错误码表：把项目错误码枚举整理成表格——错误码 | 含义 | 触发条件 | 调用方建议动作；区分"调用方可修复"（如参数错误）与"需联系服务方"（如系统异常）三、变更记录（CHANGELOG）：按"日期 | 版本 | 变更内容 | 影响方"格式，为本次接口变更生成条目——收货确认接口新增 Idempotency-Key 请求头（破坏性变更，需调用方配合）、回执回调接口新增（新增能力）【接口定义】{{粘贴前两步生成的 OpenAPI YAML}}【错误码枚举】{{粘贴 Day 17 错误码表}}

错误场景的示例 JSON，校审后是这个样子——注意它精确到了业务语义，而不是笼统的"error"：

// 场景：单据状态=已入库，再次确认收货（状态机非法迁移）{  "code": "RCPT-1001",  "message": "收货单已完成入库，禁止重复确认",  "data": null,  "traceId": "9f8e7d6c-5b4a-3210"}// 调用方动作：提示用户刷新单据状态，禁止自动重试

CHANGELOG 最有价值的一条是"破坏性变更"标注：新增幂等键请求头对所有存量调用方是破坏性变更，必须在变更记录里标明影响方和配合动作——这一条是 AI 生成、人来审的重点，漏了它，联调现场就会有调用方拿着旧文档报障。

七、组装成文与校审：合同三查

产出齐了，按这个骨架组装《采购管理服务 v2.5 接口文档》：鉴权总述（token 怎么拿、放哪、过期怎么办）→ 接口列表总览 → 每个接口（OpenAPI 定义 + 示例 JSON + 错误场景）→ 全局错误码表 → 变更记录。组装后让 AI 做一遍一致性校审：示例 JSON 的每个字段都能在 schema 里找到定义、错误码表与各接口引用完全一致、CHANGELOG 覆盖所有与上一版本的差异。

最后是人工校审的三查——这是 AI 最容易翻车、调用方最容易踩坑的三处：

合同三查：① 字段与约束——逐字段对照 DTO 和 DDL：类型、长度、必填、枚举值，AI 脑补的字段和默认放宽的约束都在这里现形；② 鉴权方式——token 获取方式、传递位置、过期码与刷新约定，回调类接口与用户类接口的鉴权差异必须写清；③ 幂等性——哪些接口幂等、幂等键怎么生成怎么传、重复提交返回什么，收货确认和回执回调这两条异步链路的接口，幂等约定一条都不能含糊。

至此，"系统之间的合同"也进了文档链：从代码提炼的、从需求定义的接口，统一收敛成一份 OpenAPI 文件，带着示例、错误码和变更记录——前端拿它配 Mock，测试拿它写接口用例（直接进 Day 18 的用例集），供应商拿它对接，变更留痕可查。一份机器可读的接口文档，就是多个角色共用的单一事实源。

明天 Day 23，我们把文档链延伸到系统的"售后服务"：用 AI 编写运维手册与 SOP——日常巡检清单、故障处理五步结构、应急预案分级响应，再把历史故障记录反推成 SOP，让踩过的每一个坑都固化成文档。

本篇核心回顾

① 接口文档三宗罪：过期、不完整、格式不一——过期比缺失更危险
② OpenAPI 把接口从散文变条款：机器可读，一次编写四处使用
③ 两条路径：从代码提炼补文档，从需求定义做契约先行
④ 出处分离：AI 产出必须区分"有出处的"与"待人工确认的"
⑤ 示例让文档可试：正常 + 错误场景各配 JSON，错误码全局统一
⑥ 合同三查：字段约束、鉴权方式、幂等性——破坏性变更必须留痕

· · · · · ·

——本篇小结——

今天用两条路径打通了接口文档的生成：已上线的收货确认接口由 AI 从 Controller 代码提炼出 OpenAPI 定义，新增的回执回调接口走契约先行、评审后开发；再配上正常与错误场景的示例 JSON、全局错误码表和带破坏性变更标注的 CHANGELOG，一份"可试、可查、可追溯"的接口合同就齐了。人做的核心动作是三查——字段约束、鉴权方式、幂等性，把 AI 的脑补挡在合同之外。

明天 Day 23，进入交付后的长期战场：用 AI 编写运维手册与 SOP——巡检清单、故障处理五步法、应急预案分级，把"人走了经验就丢了"的运维知识，固化成人人可执行的文档。

今日互动：你对接过最离谱的接口文档长什么样？是字段全靠猜、错误码靠试，还是文档里的接口压根已经下线了？