openapi

OpenAPI 规范

此技能提供有关使用 OpenAPI 规范（OAS）文档的指导。

当前版本： OpenAPI 3.2.0（2025 年 9 月）

快速导航

• 文档结构：references/document-structure.md
• 操作与路径：references/operations.md
• Schema 与数据类型：references/schemas.md
• 参数与序列化：references/parameters.md
• 安全性：references/security.md

适用场景

• 创建新的 OpenAPI 规范文档
• 描述 HTTP API 端点
• 定义请求/响应 Schema
• 配置 API 安全性（OAuth2、API 密钥、JWT）
• 验证现有 OpenAPI 文档
• 根据规范生成客户端/服务端代码

文档结构概览

OpenAPI 文档的根节点 MUST 是 OpenAPI Object 或 Schema Object。

必需字段

openapi: 3.2.0 # REQUIRED: OAS version
info: # REQUIRED: API metadata
  title: My API
  version: 1.0.0

完整结构

openapi: 3.2.0
info:
  title: Example API
  version: 1.0.0
  description: API description (supports CommonMark)
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get:
      summary: List resources
      responses:
        "200":
          description: Success
components:
  schemas: {}
  parameters: {}
  responses: {}
  securitySchemes: {}
security:
  - apiKey: []
tags:
  - name: resources
    description: Resource operations

核心对象参考

Info Object

info:
  title: Example API # REQUIRED
  version: 1.0.0 # REQUIRED (API version, NOT OAS version)
  summary: Short summary
  description: Full description (CommonMark)
  termsOfService: https://example.com/terms
  contact:
    name: API Support
    url: https://example.com/support
    email: [email protected]
  license:
    name: Apache 2.0
    identifier: Apache-2.0 # OR url (mutually exclusive)

Server Object

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://{environment}.example.com:{port}/v1
    description: Configurable
    variables:
      environment:
        default: api
        enum: [api, staging, dev]
      port:
        default: "443"

Path Item Object

/users/{id}:
  summary: User operations
  parameters:
    - $ref: "#/components/parameters/userId"
  get:
    operationId: getUser
    responses:
      "200":
        description: User found
  put:
    operationId: updateUser
    requestBody:
      $ref: "#/components/requestBodies/UserUpdate"
    responses:
      "200":
        description: User updated

Operation Object

get:
  tags: [users]
  summary: Get user by ID
  description: Returns a single user
  operationId: getUserById # MUST be unique across all operations
  parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
  responses:
    "200":
      description: Success
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/User"
    "404":
      description: Not found
  security:
    - bearerAuth: []
  deprecated: false

Schema 示例

基本对象

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        age:
          type: integer
          minimum: 0

使用 allOf 组合

ExtendedUser:
  allOf:
    - $ref: "#/components/schemas/User"
    - type: object
      properties:
        role:
          type: string
          enum: [admin, user, guest]

使用 oneOf 实现多态

Pet:
  oneOf:
    - $ref: "#/components/schemas/Cat"
    - $ref: "#/components/schemas/Dog"
  discriminator:
    propertyName: petType
    mapping:
      cat: "#/components/schemas/Cat"
      dog: "#/components/schemas/Dog"

可空与可选

# OAS 3.1+ uses JSON Schema type arrays
properties:
  nickname:
    type: [string, "null"] # nullable

参数位置

位置	in 值	说明
路径	path	MUST 为 required: true
查询	query	标准查询参数
查询字符串	querystring	整个查询字符串作为单个参数
标头	header	名称不区分大小写
Cookie	cookie	Cookie 值

参数样式

样式	in	类型	示例（color=blue,black）
simple	path	数组	blue,black
form	query	基本类型/数组/对象	color=blue,black
matrix	path	基本类型/数组/对象	;color=blue,black
label	path	基本类型/数组/对象	.blue.black
deepObject	query	对象	color[R]=100&color[G]=200

安全方案

API 密钥

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header # header, query, or cookie
      name: X-API-Key

Bearer 令牌（JWT）

bearerAuth:
  type: http
  scheme: bearer
  bearerFormat: JWT

OAuth2

oauth2:
  type: oauth2
  flows:
    authorizationCode:
      authorizationUrl: https://auth.example.com/authorize
      tokenUrl: https://auth.example.com/token
      scopes:
        read:users: Read user data
        write:users: Modify user data

应用安全设置

# Global (all operations)
security:
  - bearerAuth: []

# Per-operation
paths:
  /public:
    get:
      security: [] # Override: no auth required
  /protected:
    get:
      security:
        - oauth2: [read:users]

Reference Object

使用 $ref 避免重复：

# Reference within same document
$ref: '#/components/schemas/User'

# Reference to external file
$ref: './schemas/user.yaml'
$ref: './common.yaml#/components/schemas/Error'

Components Object

可复用的构建块：

components:
  schemas: # Data models
  responses: # Reusable responses
  parameters: # Reusable parameters
  examples: # Reusable examples
  requestBodies: # Reusable request bodies
  headers: # Reusable headers
  securitySchemes: # Security definitions
  links: # Links between operations
  callbacks: # Webhook definitions
  pathItems: # Reusable path items

最佳实践检查清单

• 为所有操作添加 operationId（唯一且便于编程使用）
• 使用 $ref 引用可复用组件
• 添加有意义的 description 字段（支持 CommonMark）
• 定义所有可能的响应代码
• 为复杂 Schema 添加 examples
• 使用 tags 对相关操作分组
• 使用 deprecated: true 标记已弃用的操作
• 为 info.version 使用语义化版本控制

重要禁令

• 不要省略 openapi 和 info 字段（它们是 REQUIRED）
• 不要使用重复的 operationId 值
• 不要在 Reference Objects 中将 $ref 与同级属性混用
• 不要使用缺少 required: true 的路径参数
• 新 API 中不要使用隐式 OAuth2 流（已弃用）
• 不要忘记为受保护的端点配置安全性

验证

文件命名

• 入口文档：openapi.json 或 openapi.yaml（推荐）
• 格式：JSON 或 YAML（等效）
• 所有字段名均区分大小写

常见验证错误

错误	修复
缺少必填字段	添加 openapi、info.title、info.version
operationId 无效	使用唯一且有效的标识符
路径参数不在路径中	确保 {param} 与参数名称匹配
路径模板重复	移除冲突的 /users/{id} 与 /users/{userId}
$ref 无效	检查 URI 语法及目标是否存在

链接

• 文档
• 发行版本
• GitHub
• 学习门户