API 设计辅助——用 AI 从需求直接生成 OpenAPI Spec

老张2026/4/30大约 7 分钟

API 设计辅助——用 AI 从需求直接生成 OpenAPI Spec

适读人群：后端工程师、做API设计的Tech Lead | 阅读时长：约12分钟 | 核心价值：AI辅助API设计的完整流程，含质量评估方法和AI能做什么不能做什么

有一段时间，我们团队 API 设计的过程是这样的：PM 写需求文档，后端工程师看完之后开会讨论，讨论完写 Swagger 注解，前端来问"这个字段是什么意思"，后端修改，再确认……

一个中等复杂度的功能，API 设计阶段来回拉扯一周是常事。

后来我引入了 AI 生成 OpenAPI Spec 草稿的做法，把这个流程压缩到了 2 天。但更重要的变化是：讨论的质量变了。

以前大家在会议里讨论"这个接口该叫什么名字""这个字段放进 body 还是 query"，浪费在这些低价值问题上的时间太多。现在 AI 先给出一个草稿，大家围绕具体的 Spec 内容讨论，效率和深度都提升了很多。

工作流概述

需求文档
    |
    v
AI 生成 OpenAPI Spec 草稿
    |
    v
工程师 Review（接口合理性、命名规范、安全设计）
    |
    v
AI 辅助完善（根据 Review 意见修改）
    |
    v
前后端确认
    |
    v
落地为代码

关键点：AI 在这个流程里是"草稿生成器"和"修改执行器"，不是"设计决策者"。设计决策永远在人这里。

实际案例：从需求到 Spec

下面用一个真实的需求（脱敏后）来演示整个过程。

需求文档（原文节选）：

功能：用户订单管理

1. 用户可以查看自己的订单列表，支持按状态筛选（待支付/已支付/已发货/已完成/已取消）
   可以按时间倒序，支持分页，每页最多20条

2. 用户可以查看某个订单的详情，包括订单基本信息、商品列表、收货地址、支付信息

3. 用户可以取消还没有支付的订单

4. 管理员可以查看所有用户的订单，额外支持按用户ID、按创建日期范围筛选

需要注意：
- 订单详情里的支付信息（卡号后四位、支付渠道）只有订单所有者和管理员能看
- 取消订单要记录取消原因

给 AI 的 Prompt：

基于以下需求文档，生成 OpenAPI 3.1 格式的 Spec（YAML格式）。

要求：
1. RESTful 命名规范
2. 包含完整的请求体、响应体 Schema 定义（用 $ref 复用）
3. 包含常见错误码（400/401/403/404/500）
4. 请求参数要有 description
5. 安全方面的考虑要体现在 Spec 里（比如哪些接口需要认证、哪些有权限区分）
6. 不确定的设计决策要在注释里标注 [REVIEW NEEDED]

[需求文档内容粘贴]

AI 生成的 Spec（节选）：

openapi: 3.1.0
info:
  title: 订单管理 API
  version: 1.0.0

paths:
  /api/v1/orders:
    get:
      summary: 获取订单列表
      description: 普通用户只能获取自己的订单，管理员可获取所有用户的订单
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          description: "订单状态筛选，多个状态用逗号分隔 [REVIEW NEEDED: 考虑是否用多值参数 ?status=A&status=B]"
          required: false
          schema:
            type: string
            example: "PAID,SHIPPED"
        - name: userId
          in: query
          description: "用户ID，仅管理员可用，普通用户传此参数返回403"
          required: false
          schema:
            type: string
        - name: startDate
          in: query
          description: 创建日期范围开始（ISO 8601）
          required: false
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: 创建日期范围结束（ISO 8601）
          required: false
          schema:
            type: string
            format: date
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 20
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/Forbidden'

  /api/v1/orders/{orderId}:
    get:
      summary: 获取订单详情
      security:
        - bearerAuth: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetail'
        "403":
          description: "无权查看此订单 [REVIEW NEEDED: 是返回403还是404？返回404可以防止用户枚举其他订单ID]"
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'

  /api/v1/orders/{orderId}/cancel:
    post:
      summary: 取消订单
      description: 只能取消 PENDING_PAYMENT 状态的订单，只有订单所有者可以操作
      security:
        - bearerAuth: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                reason:
                  type: string
                  description: 取消原因
                  maxLength: 200
      responses:
        "200":
          description: 取消成功
        "400":
          description: 订单状态不允许取消（已支付/已发货等）
        "403":
          $ref: '#/components/responses/Forbidden'

components:
  schemas:
    OrderDetail:
      type: object
      properties:
        orderId:
          type: string
        status:
          type: string
          enum: [PENDING_PAYMENT, PAID, SHIPPED, COMPLETED, CANCELLED]
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        shippingAddress:
          $ref: '#/components/schemas/Address'
        paymentInfo:
          description: "仅订单所有者和管理员可见，其他情况下此字段为null [REVIEW NEEDED: 是否用独立接口返回支付信息？]"
          allOf:
            - $ref: '#/components/schemas/PaymentInfo'
            - nullable: true

Review 阶段：工程师要检查什么

AI 生成的草稿不能直接用，Review 阶段要检查这几类问题：

1. 安全漏洞

AI 通常能发现明显的安全设计问题（注意到了"普通用户传 userId 应该返回 403"），但也可能漏掉不明显的问题。

我 Review 这份 Spec 时发现的安全问题：

订单列表接口，普通用户不传 userId 时，应该自动用当前登录用户的 ID，不应该由前端传入。这个设计 AI 没有显式说明，容易被前端误解。
AI 标注的 [REVIEW NEEDED] 里提到了"403 vs 404"的问题，这是个值得认真考虑的安全设计点：返回 404 能防止用户枚举其他订单 ID，但也会让调试更难。我们最终选择了 404。

2. 命名一致性

AI 给的命名不一定符合你团队的约定。比如：

分页参数，有的团队用 page/size，有的用 pageNum/pageSize，有的用 offset/limit
时间字段，有的用 createdAt，有的用 createTime，有的用 gmtCreate

这类命名规范 AI 猜不准，必须人工统一。

3. 遗漏的场景

AI 根据需求文档生成，但需求文档本身可能有遗漏。这份 Spec 里我发现漏了：

取消订单的幂等性处理（重复取消已取消的订单应该返回什么？）
管理员取消订单的接口（需求里只提了用户取消，管理员怎么取消没说）

这两个遗漏是需求文档本身的问题，不是 AI 的错，但在 Review Spec 时很容易发现。

用 AI 评估 Spec 质量

除了人工 Review，我还会用一个专门的 Prompt 让 AI 自检：

请以一个资深后端工程师的角度，审查以下 OpenAPI Spec，重点检查：

1. REST 设计合规性：命名是否符合 RESTful 规范，动词是否正确使用
2. 安全性：是否有权限控制遗漏，是否有信息泄漏风险
3. 错误码：错误码是否覆盖了常见的业务场景
4. 一致性：命名风格、参数风格、响应格式是否一致
5. 可扩展性：设计是否为未来可能的扩展留了空间

对每个问题给出具体的行号和修改建议。

[Spec内容]

这个自检步骤通常能再发现 2-3 个我人工 Review 漏掉的问题。两轮 Review 结合效果比单轮好。

AI 在这个环节能做什么、不能替代什么

AI 能做的：

快速生成完整的 Spec 框架，避免从空白开始
记住 OpenAPI 3.1 的语法细节（你不用记 $ref 怎么写）
发现一些设计上的显性问题（并用 [REVIEW NEEDED] 标注）
执行修改（"把所有分页参数从 page/size 改成 pageNum/pageSize"这种批量修改）

AI 不能替代的：

了解你团队的 API 规范和历史约定
判断哪些设计决策需要和业务对齐
评估接口设计对前端的开发体验的影响（这需要前端参与）
做安全设计决策（403 vs 404 这类决策有业务和安全的权衡，不是技术问题）

一句话总结：AI 帮你把"从 0 到初稿"这段距离跑完，剩下的"从初稿到正式版"的距离，还得人来跑。

但"从 0 到初稿"本来就占了大量时间，这段时间省下来，价值很实在。