AI 辅助 API 设计：从需求描述到 OpenAPI 文档的自动化生成链路
AI 辅助 API 设计：从需求描述到 OpenAPI 文档的自动化生成链路
一、API 设计的第一步不是写接口，而是想清楚「谁来用、用什么、出错怎么办」
AI 辅助 API 设计的真正价值，不在于生成一段 OpenAPI 格式的 YAML 文档，而在于它能帮助工程师在写代码之前，先把 API 的契约想清楚。一个好的 API 设计，需要回答一系列问题：这个接口的调用者是谁（前端、第三方开发者、内部服务）？请求参数应该如何校验？错误应该如何返回？版本如何管理？这些问题的答案，决定了 API 的可用性、可维护性和演进能力。
传统的 API 设计流程里，这些问题往往是在写代码的过程中才逐渐想清楚的——先写一个 rough 的接口，前端调用时发现问题，再改接口，再改前端，来回几次才稳定。AI 辅助的流程，是在写代码之前，用自然语言描述需求，让 AI 生成多个备选的 API 设计方案，工程师从中选择最合适的一个，然后用工具生成 OpenAPI 文档、类型定义和 Mock 服务。这样前端和后端可以在同一份契约上并行开发，而不是互相等待。
但这个流程有一个关键前提：AI 生成的 API 设计必须符合团队的规范和最佳实践。如果团队的 API 风格是 RESTful 的，AI 就不能生成 GraphQL 或者 RPC 风格的接口；如果团队的错误响应格式是{ code, message, details }，AI 生成的接口就必须遵循这个格式。这需要在提示词里明确约束，或者更好——用自定义的 System Prompt 或者 API 设计规则文件来约束 AI 的输出。
二、从需求到 API 设计：AI 辅助的生成链路
flowchart LR A[自然语言需求描述] --> B[AI 生成 API 设计方案] B --> C[人工评审与选择] C --> D[AI 生成 OpenAPI 文档] D --> E[生成类型定义] E --> F[生成 Mock 服务] F --> G[前后端并行开发] C -->|反馈| B这条链路的核心价值，是「在前端和后端开始写代码之前，就把接口契约确定下来」。前后端基于同一份 OpenAPI 文档并行开发，前端用 Mock 服务模拟响应，后端按照文档实现逻辑，最后对接时出问题的概率会大幅降低。
以一个简单的「用户认证」功能为例，需求描述可能是：「用户可以通过邮箱和密码登录，成功后返回一个 Token；如果邮箱不存在或者密码错误，返回对应的错误信息；Token 有效期为 7 天，支持刷新。」
基于这个需求，AI 可以生成多个设计方案。方案 A 是 RESTful 风格：POST /api/auth/login，请求体{ email, password }，响应{ token, expiresAt }，错误响应用 HTTP 状态码 +{ error, message }格式。方案 B 是 JSON-RPC 风格：一个统一的POST /api/rpc端点，请求体指定method: "auth.login"。方案 C 是 GraphQL 风格：一个mutation login(email: String!, password: String!): AuthPayload。
这三个方案各有优劣，选择哪个取决于团队的技术栈和规范。AI 可以生成方案，但选择必须由人工来做——因为只有人工知道团队的上下文。
三、OpenAPI 文档的自动化生成与维护：从代码生成文档，还是从文档生成代码？
OpenAPI 文档的维护，有两种主流模式：「代码优先」（Code First）和「文档优先」（Design First）。
代码优先模式：先写代码（如用 TypeScript 类型定义，或者用框架的装饰器如@nestjs/swagger），然后从代码里提取 OpenAPI 文档。这种模式的优点是「文档不会过时」——因为文档是从代码生成的，代码改了，文档跟着改。缺点是「设计时没有完整的契约视图」——你看不到完整的 API 设计，只能看到零散的接口定义。
文档优先模式：先写 OpenAPI 文档（YAML 或 JSON），然后从文档生成代码（类型定义、Mock 服务、甚至服务端骨架）。这种模式的优点是「设计时有完整的契约视图」，可以先用文档和前端讨论接口设计，确认后再开始写代码。缺点是「文档可能和代码不同步」——如果团队没有纪律，代码改了但文档没更新，文档就会变成谎言。
AI 辅助的引入，让这两种模式的边界变得模糊。你可以先用自然语言描述需求，让 AI 生成 OpenAPI 文档草稿，然后基于文档生成类型定义和 Mock 服务（文档优先）；也可以在已有代码的基础上，让 AI 分析代码和注释，生成或更新 OpenAPI 文档（代码优先的辅助）。工程上推荐的做法是：新接口用文档优先，已有接口用代码优先 + AI 辅助维护文档。
以下是一个用 AI 辅助从需求生成 OpenAPI 文档的提示词示例：
你是一个 API 设计专家。请根据以下需求，生成 OpenAPI 3.0 格式的 API 文档。 ## 需求 [粘贴需求描述] ## 团队规范 - 使用 RESTful 风格，URL 用复数名词（如 /users, /orders） - 错误响应格式: { "error": { "code": "string", "message": "string", "details": {} } } - 成功响应用 HTTP 状态码，4xx 用于客户端错误，5xx 用于服务器错误 - 分页参数统一用 page 和 pageSize，分页响应格式: { "data": [], "pagination": { "page": 1, "pageSize": 20, "total": 100 } } - 所有字符串字段用 maxLength 限制，所有必填字段用 required 标记 请生成完整的 OpenAPI YAML，包括 schemas、requestBody 和 responses。四、AI 生成 API 的质量控制：校验、测试与演进
AI 生成的 OpenAPI 文档，必须进行人工校验。校验的重点不是「格式是否正确」（这个可以用工具自动检查），而是「设计是否合理」。以下几个问题，是人工校验时应该逐一确认的：
这个接口是否做到了「单一职责」？一个接口是否承担了多个不相关的功能？如果是，考虑拆分成多个接口。
参数设计是否合理？查询参数是否支持过滤、排序和分页？路径参数是否用了正确的数据类型？请求体的嵌套层级是否太深？
错误处理是否完整？每个可能失败的点，是否都有对应的错误响应？错误码是否有文档？客户端能否根据错误码做不同的处理？
版本管理策略是否明确？这个接口是 v1 还是 v2？如果未来要改这个接口，如何做到向后兼容？
除了人工校验，还应该用自动化工具来验证 OpenAPI 文档的正确性和完整性。openapi-generator可以根据 OpenAPI 文档生成客户端 SDK 和服务端骨架，如果生成失败或者生成的代码有明显问题，说明文档有错误。prism可以根据 OpenAPI 文档启动一个 Mock 服务器，用来验证请求和响应是否符合文档定义。
API 的演进也是一个长期问题。AI 可以辅助做「变更影响分析」：当你修改一个 OpenAPI 文档时，AI 可以分析哪些字段被修改了、哪些是破坏性变更、哪些客户端可能受影响。这个分析对于管理 API 版本和做向后兼容的演进非常有价值。
五、总结
AI 辅助 API 设计的核心价值，在于把「想清楚接口契约」这个过程提前，让前后端在写代码之前就对齐接口设计，减少后期返工。从需求描述到 OpenAPI 文档，从文档到类型定义和 Mock 服务，这条自动化链路能显著提升开发效率。但 AI 生成的 API 设计必须经过人工校验，重点确认接口职责、参数设计、错误处理和版本策略。文档优先还是代码优先，不是非此即彼的选择——新接口用文档优先，已有接口用代码优先加 AI 辅助维护，是工程上最务实的做法。