AI 时代,API 文档的读者有一半是机器

// AI 生成的代码——看起来有模有样async function getAbnormalOrders() {  const res = await fetch("https://api.internal.com/order/list", {    method: "POST", // ❌ 实际是 GET，文档没写清，AI 猜的    headers: { Authorization: "Bearer " + TOKEN }, // ❌ 实际用 X-Api-Key 头    body: JSON.stringify({      status: "abnormal", // ❌ 实际枚举值是 "EXCEPTION"      page: 1, // ❌ 实际分页字段叫 pageNo，且从 0 开始      startTime: "2026-08-14", // ❌ 实际要 Unix 毫秒时间戳    }),  });  const data = await res.json();  return data.list.map((o) => o.orderNo); // ❌ 实际字段是 order_no}

查询订单列表地址：/order/list参数：  status    订单状态  page      页码  时间范围   起止时间返回：订单列表数组

文档没写清的 -> 问后端（"status 都有哪些值来着？"）文档写错的   -> 试一下（发个请求看报错，再调整）约定俗成的   -> 靠经验（"时间戳嘛，估计是毫秒"）

# openapi.yaml（节选）——机器眼里的"全部事实"paths:  /order/list:    get: # 方法明确：GET，不用猜      summary: 查询订单列表      parameters:        - name: status          in: query          schema:            type: string            # 关键：枚举值穷举在这里，AI 永远不会猜出 "abnormal"            enum: [UNPAID, PAID, SHIPPED, COMPLETED, EXCEPTION, REFUNDING]          description: 订单状态筛选，不传表示全部        - name: pageNo          in: query          schema:            type: integer            minimum: 0            default: 0 # 关键：起始页写死，不用试        - name: startTime          in: query          schema:            type: integer            format: int64          description: 起始时间，Unix 毫秒时间戳 # 单位写明        - name: endTime          in: query          schema:            type: integer            format: int64          description: 结束时间，Unix 毫秒时间戳      responses:        "200":          description: 成功          content:            application/json:              schema:                type: object                properties:                  list:                    type: array                    items:                      type: object                      properties:                        order_no:                          type: string # 字段名精确到蛇形命名                        amount_cents:                          type: integer

// 典型的"给人看都费劲"的错误响应{  "code": 500,  "message": "系统异常"}

// HTTP 400 —— 状态码先分对错类别{  "error": {    "code": "INVALID_ORDER_STATUS", // 机器可分支处理的稳定标识    "message": "status 参数取值不合法", // 给人看的描述    "details": {      "received": "abnormal", // 你传了什么      "allowed": ["UNPAID", "PAID", "SHIPPED", "COMPLETED", "EXCEPTION", "REFUNDING"]      // ^^^ 关键：合法值直接给出来，调用方可以自我修正    },    "retryable": false // 明确告诉调用方：别重试，改了参数再来  }}

async function callOrderApi(params) {  const res = await fetch(buildUrl(params));  const body = await res.json();  if (res.ok) return body;  const err = body.error;  // 机器可执行的纠错逻辑：  if (err.code === "INVALID_ORDER_STATUS") {    // 从错误详情里取出合法值，映射后自动重试    params.status = mapToAllowed(params.status, err.details.allowed);    return callOrderApi(params); // 修正后重发，一次成功  }  if (err.retryable) {    await sleep(1000);    return callOrderApi(params); // 服务端瞬时故障，允许重试  }  throw new Error(`${err.code}: ${err.message}`); // 真错误，抛给人}

错误响应是 "系统异常"：  调用 -> 失败 -> 原样重试 -> 失败 -> 放弃 -> 找人来修错误响应是结构化的：  调用 -> 失败 -> 读到 allowed 枚举 -> 自我修正 -> 成功

{  "amount": 1999,       // 1999 什么？元？角？分？  "created_at": 1755763200, // 秒还是毫秒？  "price": "19.99",     // 怎么又是字符串？  "expire": 86400       // 时长还是截止时间？单位是？}

{  "amount_cents": 1999, // 单位进名字，想误读都难  "created_at": "2026-08-21T08:00:00Z", // ISO 8601 字符串，没有歧义  "price_yuan": 19.99, // 或统一用 amount_cents 风格，二选一，全系统一致  "expire_seconds": 86400 // 时长还是时点、什么单位，名字里说清}

# openapi.yaml（节选）order_no:  type: string  example: "SO20260821000123" # 示例一眼暴露了编号格式amount_cents:  type: integer  example: 1999 # 配合名字，双重确认"单位是分"created_at:  type: string  format: date-time  example: "2026-08-21T08:00:00Z"

□ 有没有 OpenAPI / JSON Schema 定义，并且和真实接口保持一致？  （"有但过时"比"没有"更糟——机器会照着错的契约自信地犯错）□ 所有枚举字段，合法值有没有穷举出来？□ 错误响应有没有结构化的 code？合法值、是否可重试，机器能拿到吗？□ 金额、时间、比例这些字段，单位和格式是写在名字里，还是靠口头约定？□ 每个接口有没有至少一个真实的请求 + 响应示例？□ 鉴权方式（用什么头、什么格式、怎么获取）写了吗？□ 分页方案（字段名、起始值、每页上限）写了吗？