SuperAPI AI Directory

openapi-mock

Coding & development

View repository

Updated 10-16 09:31

About this skill

OpenAPI Contract and Mock

Reference sources:OpenAPI 3.1 Specification、Stoplight Studio

Applicable scenarios

  • The final step of API design
  • Output a machine-readable contract
  • Mock service setup
  • Handoff to frontend/backend/QA/security/documentation

Core principles

1. OpenAPI 是真理来源(Source of Truth)
   不是文档的附属,是契约本身
   代码、Mock、文档都从 OpenAPI 生成
  1. Complete Schema Every field has a type, constraints, and examples You can't just stop at type: object

  2. Examples cover all paths Success / failure / boundary / insufficient permissions / rate limiting

  3. Markdown documentation ≠ a substitute Markdown is for humans, OpenAPI is for machines


## OpenAPI 3.1 完整结构

```yaml
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 design points

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

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

Example coverage

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 service

Tool selection

轻量级:
  - Stoplight Prism(基于 OpenAPI 自动生成)
  - Mockoon
  - JSON Server

完整服务:
  - Apifox(中文友好)
  - Postman Mock Servers
  - WireMock

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

Mock data requirements

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

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

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

Downstream handoff protocol

Reference sources:OpenAPI Specification、Stripe API Design Guide、GitHub REST API Guidelines

Three elements of handoff

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

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

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

Handoff checklist for each downstream workflow

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

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

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

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

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

Handoff quality self-check

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

Workflow

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

Quality self-check

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

Common pitfalls

  1. OpenAPI written crudely——type: object with no properties
  2. No example——the frontend doesn't know what the fields look like
  3. Examples only cover the success path——the frontend doesn't know the error format
  4. Mock uses fake data——Lorem Ipsum / hello world
  5. OpenAPI and Markdown are inconsistent——QA doesn't know which to trust
  6. Mock service returns 200——no error responses are mocked
  7. No handoff documentation——the frontend gets the OpenAPI and doesn't know how to use it
  8. No consideration for version evolution——OpenAPI has no version

Supporting templates

  • templates/api-design-brief-template.md — OpenAPI skeleton template
  • templates/openapi-handoff-template.md — handoff package template
  • templates/mock-contract-template.md — Mock data template

Collaboration with other skills

上游(汇总):
  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)