AI 辅助 API 设计：从契约到文档
API 设计的好坏，往往在第一个调用方接入时才暴露：路径不一致、错误格式各写一套、版本一升级就全链路报错。与其等联调阶段返工，不如把”契约先行”做扎实，并用 AI 把重复劳动从资源建模一路推进到文档与 SDK。本文给出可落地的决策清单、可复制的提示词，以及一份贯穿全流程的工具视角。
API 设计的关键决策
在让 AI 动手之前，先要把四类决策想清楚。AI 擅长”按规矩填空”，但规矩本身需要人来定。
资源建模
先把领域拆成名词性的”资源”，而不是动作。一个订单系统里，资源是 orders、order-items、customers，而不是 createOrder、getOrderList。用资源做主语，接口才具备可组合性：对同一个资源可以挂不同的 HTTP 方法，前端也能用统一的缓存与失效策略。
给 AI 的提示词可以这样写：
我有一个电商后台，核心实体有：用户、购物车、订单、商品、优惠券。
请把它建模成 RESTful 资源，列出每个资源的字段与相互引用关系，
输出成资源清单（资源名 / 关键字段 / 与其他资源的关系）。
不要写具体接口，只做建模。
路径命名
路径命名要稳定、可预测、不暴露实现。几条经验法则：
- 用复数名词表示集合：
/orders而非/order。 - 层级表达从属关系：
/customers/{id}/orders。 - 用连字符而非下划线或驼峰：
/order-items优于/orderItems。 - 不在路径里塞动词，动作交给 HTTP 方法表达。
路径一旦发布就几乎不可改，所以这一步值得和 AI 多轮推敲，再人工拍板。
状态码
状态码是 API 的”第一句回应”，必须语义正确。常见约定：
| 场景 | 状态码 |
|---|---|
| 创建成功 | 201 Created |
| 异步受理 | 202 Accepted |
| 请求格式错误 | 400 Bad Request |
| 未认证 | 401 Unauthorized |
| 无权限 | 403 Forbidden |
| 资源不存在 | 404 Not Found |
| 幂等冲突 | 409 Conflict |
| 服务端错误 | 500 Internal Server Error |
要求 AI 在生成契约时，每个响应都显式声明状态码与对应 schema，而不是只写 200。
版本管理
版本放哪里，团队常有分歧。主流做法是放在路径前缀（/v1/orders），对网关友好、易于观测；也可以放在请求头，但对调试不友好。无论选哪种，关键是”新增不破旧”：新增字段可向后兼容，破坏性变更必须升版本。让 AI 在评审阶段专门检查”本次改动是否破坏 v1 兼容性”。
用 AI 生成 OpenAPI/Swagger 契约与示例
契约是后续一切（文档、SDK、测试桩）的源头。把前面定好的决策喂给 AI，让它产出 OpenAPI 描述文件。
提示词思路：先给资源建模结果，再要求输出符合 OpenAPI 3.x 的 YAML，明确每个操作的 operationId、请求体、成功与错误响应、以及至少一个示例。下面是一份”最小但可用”的 YAML 示例：
# OpenAPI 3.1 最小契约：订单创建接口
openapi: 3.1.0
info:
title: 订单服务
version: 1.0.0
paths:
/orders:
post:
# 创建订单，要求客户端下发幂等键
operationId: createOrder
summary: 创建一笔订单
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/OrderCreate"
responses:
"201":
description: 订单创建成功
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"400":
description: 请求参数错误
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
OrderCreate:
type: object
required: [customer_id, items]
properties:
customer_id:
type: string
items:
type: array
items:
type: object
required: [sku, quantity]
properties:
sku:
type: string
quantity:
type: integer
minimum: 1
Order:
type: object
required: [id, status]
properties:
id:
type: string
status:
type: string
enum: [pending, paid, shipped, done]
Error:
type: object
required: [code, message]
properties:
code:
type: string
message:
type: string
request_id:
type: string
拿到这份契约后，建议让 AI 再补 2 到 3 个示例响应（正常、缺字段、越权），示例越真实，下游 SDK 与文档越贴近实际。
用 AI 生成一致的前端 SDK 与测试桩
契约写定，AI 就能基于它产出”与后端同源”的前端 SDK 和测试桩，避免前端手敲类型、各端各写一套。
生成 SDK
最直接的路径是用代码生成器吃下 OpenAPI 文件。开源的 OpenAPI Generator 支持数十种语言（TypeScript、Python、Go、Java 等），商业平台如 Stainless 则强调”地道、接近手写的 SDK”并支持持续随契约再生。给 AI 的提示词：
基于 openapi.yaml，生成 TypeScript SDK：要求导出 OrdersClient，
每个方法对应一个 operationId，入参类型来自 requestBody schema，
返回类型来自 2xx 响应 schema，错误统一抛 ApiError。
给出安装与最小调用示例。
生成测试桩
测试桩用来在后端还没就绪时，让前端和集成测试先跑起来。两种思路：
- Mock 服务：用 Prism 等工具直接按契约起一个假服务，返回示例响应。
- 调用封装：让 AI 生成带类型与默认参数的客户端封装，测试里注入假响应。
下面是一段由契约推导出的 Python 客户端封装（同时也充当调用方的测试桩）：
# 由 OpenAPI 契约生成的订单客户端封装（测试时可注入假响应）
import requests
class OrdersClient:
def __init__(self, base_url, api_key):
self.base_url = base_url.rstrip("/")
self.headers = {"Authorization": f"Bearer {api_key}"}
def create_order(self, payload, idempotency_key):
# 幂等键随请求头下发，重试同一条请求安全
headers = {**self.headers, "Idempotency-Key": idempotency_key}
resp = requests.post(
f"{self.base_url}/orders", json=payload, headers=headers, timeout=10
)
return resp
统一错误响应的结构建议写进契约并让 SDK 复用，下面是一个推荐的 JSON 形态：
{
"error": {
"code": "order_not_found",
"message": "订单不存在或当前用户无权访问",
"request_id": "req_8f2c1a73",
"details": []
}
}
用 AI 做评审：幂等、鉴权、错误规范
契约不是写完就完，交给 AI 做一轮”契约评审”，能在联调前堵住大量坑。把契约文件贴给 AI，并明确要求从三个维度检查。
幂等：写操作（POST 创建类）是否支持重试安全？是否定义了幂等键（如 Idempotency-Key）或基于业务唯一键的去重？没有幂等的创建接口在弱网重试时会重复下单。
鉴权：每个非公开操作是否声明了安全方案（securitySchemes）？令牌放在哪里、如何刷新、401 与 403 的边界是否清晰？
错误规范：所有错误响应是否共用同一结构（上面的 error 对象）？状态码与 code 是否一一对应、是否可被程序识别（不用自然语言去分支）？
可复制的评审提示词：
请评审以下 OpenAPI 契约（粘贴内容）。只聚焦三类问题：
1. 幂等：写操作是否可安全重试，是否定义幂等键或去重键。
2. 鉴权：每个操作是否声明安全方案，401/403 边界是否清楚。
3. 错误规范：错误响应是否结构统一、code 可程序化判断。
逐条给出：位置（路径/操作）、问题、为什么、建议改法。
工具链：Postman AI / Copilot / 各类 API 平台
下面仅描述能力定位，不替你做选型。
-
Postman AI（Postbot）：Postman 内的 AI 助手，可基于你正在调试的请求自动补测试脚本、写接口文档、解释报错与可视化响应。适合”在 Postman 工作流里顺手把文档和测试补齐”。（能力描述，官方文档已核验）
-
GitHub Copilot：编辑器内的 AI 结对编程，能根据上下文补全接口代码、生成单元测试、把自然语言需求转成路由与处理函数。它并不直接产出 OpenAPI 文件，但能大幅加速”按契约写实现”的过程。（通用能力，具体特性以官方文档为准，待核实）
-
Stainless：以 OpenAPI 契约为输入，生成”接近手写”的多语言 SDK、同步文档与面向 Agent 的 MCP 服务，并在契约变化时持续再生。（官方文档已核验）
-
OpenAPI Generator：开源代码生成器，吃下 OpenAPI 文件后产出客户端 SDK、服务端桩与文档，覆盖数十种语言与框架。（开源仓库已核验）
-
Prism / Spectral：Prism 按契约起 Mock 服务；Spectral 对契约做规则化校验（命名、必填、描述完整度）。二者是把”契约纪律”落到 CI 的常用搭配。（能力描述，待核实）
小结
- 先把资源建模、路径命名、状态码、版本管理四类决策定下来，AI 负责按规矩填空，规矩由人拍板。
- 用结构化的提示词让 AI 产出 OpenAPI 契约，每个响应都显式声明状态码、schema 与示例。
- 同一份契约驱动 SDK 与测试桩生成，保证前后端类型与行为同源、不 drift。
- 把契约交给 AI 做”幂等、鉴权、错误规范”三轮评审，能在联调前堵住大部分坑。
- 工具分层：Postman AI 补文档测试、Copilot 加速实现、Stainless/OpenAPI Generator 出 SDK、Prism/Spectral 守契约纪律。
- AI 产出的是”草稿与检查清单”，最终契约的兼容性与安全责任仍在人手里。
参考与延伸阅读
- OpenAPI Initiative，《OpenAPI Specification》（最新 3.2.0，定义与语言无关的 HTTP API 接口描述，作为机器可读契约）：https://spec.openapis.org/oas/latest.html —— 已核验
- Postman，《About Postbot》（Postman 内 AI 助手：补测试、写文档、解释报错、可视化响应）：https://learning.postman.com/v11/docs/getting-started/basics/about-postbot —— 已核验
- Stainless，《Studio quickstart》（以 OpenAPI 契约为输入生成多语言 SDK、文档与 MCP 服务）：https://www.stainless.com/docs/quickstart-studio —— 已核验
- OpenAPITools，《openapi-generator》（开源生成器，吃 OpenAPI 产出客户端/服务端桩/文档）：https://github.com/openapitools/openapi-generator —— 已核验
- GitHub，《GitHub Copilot documentation》（编辑器内 AI 结对编程，补全代码与测试）：https://docs.github.com/en/copilot —— 待核实（仅抓取概览，具体特性以官方更新为准）
- Stoplight，《Spectral》（契约规则化校验工具，配合 Prism 做 Mock）：https://meta.stoplight.io/docs/spectral —— 待核实