OpenAPI 设计辅助

$ref 与 components 复用示例

# OpenAPI 3.0 $ref 和 components 复用——避免内联重复定义
components:
  schemas:
    # 基础实体
    User:
      type: object
      required: [id, email]
      properties:
        id:    { type: string, format: uuid }
        email: { type: string, format: email }
        name:  { type: string, nullable: true }

    # 游标分页响应（复用）
    UserPage:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'  # 引用而非内联
        pagination:
          $ref: '#/components/schemas/CursorPage'

    # 游标分页 vs offset 分页的 OpenAPI 定义对比
    CursorPage:  # cursor-based：适合大数据集，稳定翻页
      type: object
      properties:
        nextCursor:  { type: string, nullable: true, description: null 表示最后一页 }
        hasNextPage: { type: boolean }
        limit:       { type: integer, minimum: 1, maximum: 100 }

    OffsetPage:  # offset-based：简单但大偏移性能差，需注明风险
      type: object
      description: "⚠ 大数据集时 offset 性能下降，超过10万条记录建议改用 cursor"
      properties:
        total:  { type: integer }
        page:   { type: integer, minimum: 1 }
        limit:  { type: integer, minimum: 1, maximum: 100 }

    # oneOf + discriminator：多态类型
    Notification:
      oneOf:
        - $ref: '#/components/schemas/EmailNotification'
        - $ref: '#/components/schemas/SmsNotification'
      discriminator:
        propertyName: type   # 客户端用此字段判断具体类型
        mapping:
          email: '#/components/schemas/EmailNotification'
          sms:   '#/components/schemas/SmsNotification'

从需求到可合并草稿（流程）

  [ 资源与动词清单 ]
        │
        ▼
  ┌─────────────┐     固定：info / servers / security / tags
  │  元数据骨架   │──── 约定：版本号语义、环境 URL、鉴权方式
  └─────────────┘
        │
        ▼
  ┌─────────────┐     复数路径、嵌套深度、查询与分页参数
  │ paths 草案   │──── 每个 operation：summary、operationId、参数引用
  └─────────────┘
        │
        ▼
  ┌─────────────┐     请求/响应 schema、示例、错误引用
  │ components  │────  discriminator / oneOf 写清多态规则
  └─────────────┘
        │
        ▼
  ┌─────────────┐     Spectral / CI；破坏性变更说明与迁移
  │ 校验与评审   │──── 输出告警修复项，不吞规则
  └─────────────┘

info、servers 与 securitySchemes

info.title / description 面向人类读者；contact 与 license 按仓库策略填写。servers 列出 dev/stage/prod 或占位变量，避免硬编码仅本地 URL。

# 安全方案（security schemes）完整定义示例
components:
  securitySchemes:
    BearerJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "RS256 签名的 JWT，issuer=https://auth.example.com"
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl:         https://auth.example.com/token
          scopes:
            read:items:  "读取条目列表"
            write:items: "创建和更新条目"
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key

# 全局 security（默认要求）+ per-operation 覆盖例外
security:
  - BearerJWT: []

paths:
  /public/status:
    get:
      security: []  # 覆盖全局：此接口无需认证（需注释说明原因）

• 多租户或区域前缀放在 server variable 或 path 前缀中二选一，全文档统一。

路径与资源建模

使用复数集合名（/users、/users/{userId}）；子资源嵌套不超过团队约定层数（常见 2～3）。operationId 稳定且可用于代码生成。

components 复用与约束

公共类型放入 components.schemas；请求体与响应用 $ref。required、nullable、default、enum、format（uuid、date-time 等）显式写出。

• 分页响应、错误体、空成功体各一个 schema，避免每处重写。
• 多态用 discriminator 并在 description 说明扩展策略。
• 示例与 schema 同步更新；CI 可校验 example 通过 schema。

错误体与典型状态码

统一 4xx/5xx 的 response content：RFC 7807 application/problem+json 或团队 envelope（含 code、message、details 等字段约定）。

• 列举 400、401、403、404、409、422、429、500 等与业务相关的含义。
• 429 附 Retry-After 说明（文档层描述即可）。

版本策略与破坏性变更

路径前缀（/v1）、header（Accept-Version）或子域名择一；文档中写清「何时 bump 主版本」与共存期。

Spectral 与规则集

使用团队 Spectral 规则集或 OWASP/API 规范扩展；PR 或 CI 中执行，失败时输出规则 id 与定位路径。

• Agent 对每条告警给出「改契约 / 改规则 / 豁免理由」三选一，禁止静默 ignore 而不留记录。
• 与 JSON Schema draft 版本（OpenAPI 3.0 vs 3.1）保持一致，避免混用特性。

OpenAPI 骨架实验室

选择 OpenAPI 版本、鉴权与错误体风格，填写 API 标题后生成可粘贴的 YAML 骨架；再按需补 paths 与 components。