openapi-specification

OpenAPI 规范

设计、验证和维护用于 REST API 契约的 OpenAPI 3.x 规范。 涵盖架构模式、安全方案、版本控制和代码生成集成。

何时使用此技能

• 从头创建新的 OpenAPI 规范
• 向现有规范添加端点或架构
• 检查或验证 API 契约是否正确
• 设置基于 OpenAPI 定义的代码生成
• 为大型 API 设计可复用的架构组件
• 在 API 规范中实现安全方案
• 管理 API 版本控制和弃用

快速参考

资源	用途	加载时机
references/spec-patterns.md	架构模式、安全方案、验证、版本控制、可复用组件	设计或检查规范

---

工作流

Phase 1: Design       → Define API overview, resources, and operations
Phase 2: Schema       → Build data models with reusable components
Phase 3: Validate     → Lint and verify the spec for correctness
Phase 4: Integrate    → Generate docs, SDKs, and contract tests

---

阶段 1：API 设计

编写规范前，先进行高层设计：

1. 识别资源 -- 此 API 提供哪些名词？
2. 梳理操作 -- 每个资源适用哪些 CRUD 和自定义操作？
3. 定义关系 -- 资源之间如何相互引用？
4. 规划身份验证 -- 需要哪些安全方案？
5. 制定约定 -- 命名风格、分页方式、错误格式

规范骨架

openapi: 3.1.0
info:
  title: [API Name]
  version: 1.0.0
  description: [What this API does]
paths:
  /resources:
    get:
      summary: List resources
      operationId: listResources
    post:
      summary: Create a resource
      operationId: createResource
  /resources/{id}:
    get:
      summary: Get a resource
      operationId: getResource
components:
  schemas: {}
  securitySchemes: {}

---

阶段 2：架构设计

使用 components/schemas 构建可复用的数据模型：

• 使用 $ref 引用共享架构，切勿重复定义
• 使用 allOf 进行组合，使用 oneOf / anyOf 实现多态
• 为每个架构和属性添加 example 值
• 明确使用 required 数组，不要依赖隐式行为
• 使用 type: [string, "null"]（3.1）或 nullable: true（3.0）记录可空字段

---

阶段 3：验证

提交任何规范更改前都要运行验证：

# Spectral (recommended)
spectral lint openapi.yaml

# Redocly
redocly lint openapi.yaml

# swagger-cli
swagger-cli validate openapi.yaml

常见验证问题

问题	修复方法
缺少 operationId	为每个操作添加唯一的 operationId
未使用的架构	从 components 中移除，或添加 $ref
响应缺少 description	为每个响应代码添加 description
路径中未包含路径参数	确保路径中的 {param} 与参数定义匹配
未定义 2xx 响应	为每个操作至少添加一个成功响应

---

阶段 4：集成

使用通过验证的规范生成下游产物：

• 文档：Redoc、Swagger UI、Stoplight
• 客户端 SDK：openapi-generator、autorest、orval
• 服务端桩代码：使用服务端模板的 openapi-generator
• 契约测试：Schemathesis、Dredd、Prism

---

质量检查清单

• 所有路径都有 operationId
• HTTP 方法与资源操作匹配（GET 读取、POST 创建等）
• 每个响应都有描述和架构
• 在操作级别或全局级别定义安全要求
• 为请求和响应正文提供示例
• 命名约定一致（camelCase、snake_case——任选其一）
• 为即将下线的端点设置弃用字段
• 规范通过检查工具验证，且无错误

---

反模式

• 不要内联架构；对任何需要复用的内容，都使用 $ref 引用 components/schemas
• 不要在单个规范文件中混用 API 版本
• 创建操作不要使用 200 OK；应使用 201 Created
• 不要省略错误响应架构；应一致地记录 4xx 和 5xx
• 没有明确理由时，不要使用 additionalProperties: true