OpenAPI 契约和 Mock

参考来源：OpenAPI 3.1 Specification、Stoplight Studio

适用场景

• API 设计的最后一步
• 输出机器可读的契约
• Mock 服务搭建
• 给前端/后端/QA/安全/文档的交接

核心原则

1. OpenAPI 是真理来源（Source of Truth）
   不是文档的附属，是契约本身
   代码、Mock、文档都从 OpenAPI 生成

2. Schema 完整
   每个字段都有类型、约束、示例
   不能 type: object 就完事

3. 示例覆盖所有路径
   成功 / 失败 / 边界 / 权限不足 / 限流

4. Markdown 说明 ≠ 替代品
   Markdown 给人看，OpenAPI 给机器读

OpenAPI 3.1 完整结构

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  description: |
    完整的 API 描述
    支持 Markdown
  contact:
    email: api@example.com
  license:
    name: MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://api-staging.example.com/v1
    description: Staging

# 标签分组
tags:
  - name: users
    description: 用户管理
  - name: orders
    description: 订单管理

# 全局安全
security:
  - bearerAuth: []

components:
  # 鉴权
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
  
  # Schema 定义
  schemas:
    User:
      type: object
      required: [id, email, name]
      properties:
        id:
          type: string
          example: usr_abc123
          pattern: '^usr_[a-z0-9]+$'
        email:
          type: string
          format: email
          example: user@example.com
        name:
          type: string
          minLength: 1
          maxLength: 50
          example: 张三
        created_at:
          type: string
          format: date-time
          example: 2026-01-15T10:30:00Z
    
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          example: invalid_email
        message:
          type: string
          example: 邮箱格式不正确
        trace_id:
          type: string
          example: req_abc123
  
  # 通用参数
  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1
    PageSizeParam:
      name: page_size
      in: query
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
  
  # 通用响应
  responses:
    BadRequest:
      description: 请求参数错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid_email:
              value:
                code: invalid_email
                message: 邮箱格式不正确
                trace_id: req_abc123
    Unauthorized:
      description: 未认证
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

paths:
  /users:
    get:
      tags: [users]
      summary: List users
      description: 查询用户列表，支持分页和筛选
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - name: status
          in: query
          schema:
            type: string
            enum: [active, inactive, banned]
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              examples:
                success:
                  value:
                    data:
                      - id: usr_001
                        email: user1@example.com
                        name: 张三
                        created_at: 2026-01-15T10:30:00Z
                    pagination:
                      page: 1
                      page_size: 20
                      total: 156
        '401':
          $ref: '#/components/responses/Unauthorized'
    
    post:
      tags: [users]
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, name]
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
            examples:
              normal:
                value:
                  email: new@example.com
                  name: 新用户
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: 邮箱已存在
          content:
            application/json:
              examples:
                duplicate:
                  value:
                    code: email_taken
                    message: 邮箱已被使用

Schema 设计要点

✅ 必须有：
  - type（不要省略）
  - 必填字段标 required
  - 字符串：minLength / maxLength / pattern / format
  - 数字：minimum / maximum
  - 数组：items / minItems / maxItems
  - 枚举：enum
  - 时间：format: date-time
  - example（每个字段）

❌ 避免：
  - type: object 没有 properties
  - 没有 example
  - 一个 schema 对应多种含义

示例覆盖

responses:
  '200':
    description: 成功
    content:
      application/json:
        examples:
          normal:           # 标准成功
            value: {...}
          empty:            # 空结果
            value: { data: [], pagination: { total: 0 } }
  '400':
    examples:
      invalid_email:        # 字段错误
        value: { code: invalid_email, ... }
      missing_field:        # 缺字段
        value: { code: missing_field, ... }
  '401':
    examples:
      token_expired:        # token 过期
        value: { code: token_expired, ... }
      token_invalid:        # token 无效
        value: { code: token_invalid, ... }
  '403':
    examples:
      permission_denied:
        value: { code: permission_denied, ... }
  '429':
    examples:
      rate_limit:
        value: { code: rate_limit_exceeded, ... }
        headers:
          Retry-After: 60

Mock 服务

工具选择

轻量级：
  - Stoplight Prism（基于 OpenAPI 自动生成）
  - Mockoon
  - JSON Server

完整服务：
  - Apifox（中文友好）
  - Postman Mock Servers
  - WireMock

OpenAPI 直接生成：
  npx @stoplight/prism-cli mock openapi.yaml

Mock 数据要求

必须覆盖：
  ✅ 主路径（成功响应）
  ✅ 空结果
  ✅ 校验失败
  ✅ 权限不足
  ✅ 资源不存在
  ✅ 冲突（如重复创建）
  ✅ 限流

数据真实：
  ✅ 用真实业务字段（不要 Lorem Ipsum）
  ✅ 用真实格式（手机号 138... / 邮箱 @example.com）
  ✅ 时间用 ISO 8601
  ✅ ID 符合定义的格式（usr_abc123）

数据规模：
  ✅ 列表至少 20 条（验证分页）
  ✅ 包含边界数据（最大长度字符串、特殊字符）

下游交接协议

参考来源：OpenAPI Specification、Stripe API Design Guide、GitHub REST API Guidelines

交接三要素

1. 产物（Artifact）
   - OpenAPI / Swagger 文档（机器可读）
   - Markdown 说明（人类阅读）
   - Mock 服务地址或 Mock 数据文件

2. 上下文（Context）
   - 为什么这样设计（决策背景）
   - 哪些是稳定契约，哪些可能变化
   - 已知的性能/安全/兼容约束

3. 验收标准（Acceptance）
   - 下游能否独立用 Mock 完成开发
   - 错误处理是否覆盖所有失败路径
   - 不合格时的退回机制

各下游工作流的交接清单

→ 后端工程师：
  □ OpenAPI 完整契约
  □ 资源模型和状态流转
  □ 每个端点的权限规则
  □ 幂等键和并发冲突处理规则
  □ 异步任务和 Webhook 协议
  □ 错误码和触发条件
  验收：后端能据此实现接口且通过契约测试

→ 前端工程师：
  □ OpenAPI 文档
  □ Mock 服务地址（可独立联调）
  □ 请求响应示例（成功/失败/空）
  □ 错误处理建议
  □ 分页/筛选/排序使用方式
  验收：前端能在不依赖后端的情况下完成主路径开发

→ QA 工程师：
  □ 端点清单 + 权限矩阵
  □ 成功/失败/边界/权限/并发/重试测试点
  □ Mock 数据覆盖所有路径
  □ 错误码完整列表
  验收：QA 能据此设计接口测试用例

→ 安全工程师：
  □ 认证鉴权方式
  □ 敏感字段清单和脱敏规则
  □ Webhook 签名规则
  □ 限流和滥用防护策略
  □ 租户隔离边界
  验收：安全工程师能据此评审权限和数据保护

→ 技术文档工作流：
  □ 对外 API 文档（含示例和错误码）
  □ 迁移说明（如果是版本升级）
  □ 常见问题解答
  验收：开发者能据此独立接入 API

交接质量自检

- OpenAPI 和 Markdown 说明是否一致？
- Mock 数据是否能覆盖所有错误路径？
- 如果我是前端，能不能在不问后端的情况下开发完整页面？
- 如果我是 QA，能不能直接根据契约设计测试用例？
- 错误码是否每条都有触发条件和处理建议？
- 敏感字段是否都标注了脱敏规则？

工作流程

1. 整合所有 skill 的输出
2. 写入 OpenAPI YAML
3. 定义 components（schemas / parameters / responses）
4. 为每个端点写完整的 path 定义
5. 添加详细 example（覆盖所有路径）
6. 配置 Mock 服务（Prism / Apifox）
7. 自检 OpenAPI 和 Markdown 一致性
8. 输出交接包给所有下游

质量自检

□ OpenAPI 通过 lint 检查（Spectral）
□ 每个 schema 都有 example
□ 每个端点都有成功 + 失败示例
□ 错误响应覆盖所有错误码
□ Mock 服务运行正常
□ 前端能用 Mock 独立开发
□ Markdown 说明和 OpenAPI 字段一致
□ 交接清单完整

常见坑

1. OpenAPI 写得简陋——type: object 没有 properties
2. 没有 example——前端不知道字段长什么样
3. 示例只有成功路径——前端不知道错误格式
4. Mock 用假数据——Lorem Ipsum / hello world
5. OpenAPI 和 Markdown 不一致——QA 不知道信哪个
6. Mock 服务返回 200——所有错误响应都没 mock
7. 没有交接说明——前端拿到 OpenAPI 不知道怎么用
8. 没考虑版本演进——OpenAPI 不带 version

配套模板

• templates/api-design-brief-template.md — OpenAPI 骨架模板
• templates/openapi-handoff-template.md — 交接包模板
• templates/mock-contract-template.md — Mock 数据模板

与其他 skill 的协作

上游（汇总）：
  resource-modeling → schemas
  endpoint-design → paths
  request-response → schemas / examples
  error-handling → error responses
  auth-permission → securitySchemes
  pagination-filtering → query parameters
  versioning → info.version
  idempotency-retry → headers
  webhook-async → 异步端点 / Webhook schema

下游（交付）：
  转交所有下游工作流
  作为 API 真理来源（Source of Truth）