📚 课程目录第2章 OpenAPI核心概念

2. OpenAPI 核心概念：路径、操作、参数、请求体、响应

OpenAPI 规范的核心在于用标准化的方式描述一个 HTTP API 的五个基本要素：路径（Path）、操作（Operation）、参数（Parameter）、请求体（Request Body）和响应（Response）。理解这五个概念是编写高质量接口契约的基础。

核心认知： 路径 + 操作 = 端点（Endpoint）；参数 + 请求体 = 客户端发送的内容；响应 = 服务端返回的内容。这五个元素共同构成了一个完整的 API 交互描述。

2.1 路径（Path）

路径是 API 的 URL 中除去主机地址和协议后的部分，用于定位资源。在 OpenAPI 中，路径以 / 开头，可以包含静态片段和动态模板参数。

静态路径： 固定不变的路径，如 /users、/orders。
动态路径： 包含路径参数的路径，用花括号 {} 包裹参数名，如 /users/{userId}、/orders/{orderId}/items。

路径定义在 OpenAPI 文档的 paths 对象下，每个路径对应一个相对 URL 模板。

paths:
  /users:
    # 对该路径的操作定义
  /users/{userId}:
    # 对该路径的操作定义

  设计原则： 路径应使用名词复数形式表示资源集合（如 /products），避免使用动词（如 /getProducts）。动词应通过 HTTP 方法（操作）来表达。

2.2 操作（Operation）

操作对应 HTTP 方法（GET、POST、PUT、PATCH、DELETE 等），定义在路径之下。每个操作描述了对该资源执行的一种具体行为。

HTTP 方法	典型用途	幂等性	安全性
GET	获取资源	是	是
POST	创建资源	否	否
PUT	全量更新资源	是	否
PATCH	部分更新资源	否	否
DELETE	删除资源	是	否

每个操作可以包含 operationId（唯一标识）、summary（简短描述）、parameters（参数列表）、requestBody（请求体）和 responses（响应定义）。

paths:
  /users/{userId}:
    get:
      operationId: getUserById
      summary: 根据用户ID获取用户信息
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回用户信息

2.3 参数（Parameter）

参数定义了客户端在请求中传递的附加数据。OpenAPI 支持四种参数位置（in 字段）：

参数位置	描述	示例	常见用途
path	嵌入在 URL 路径中	`/users/{userId}`	标识特定资源
query	URL 问号后的键值对	`?page=1&limit=20`	过滤、分页、排序
header	HTTP 请求头	`X-Request-Id: abc123`	认证令牌、追踪 ID
cookie	HTTP Cookie	`sessionId=xyz789`	会话管理

每个参数必须包含 name 和 in 字段，通常还需要 schema 定义数据类型和约束。

parameters:
  - name: page
    in: query
    description: 页码，从1开始
    required: false
    schema:
      type: integer
      minimum: 1
      default: 1
  - name: Authorization
    in: header
    description: Bearer token
    required: true
    schema:
      type: string

常见错误： 路径参数必须标记为 required: true，因为路径模板中的参数是 URL 的组成部分，不可省略。查询参数默认 required: false，但业务上必须的参数应显式设置为 true。

2.4 请求体（Request Body）

请求体用于 POST、PUT、PATCH 等需要向服务端发送数据的操作。在 OpenAPI 3.x 中，请求体通过 requestBody 字段定义，与参数分离，结构更清晰。

请求体包含 description、required 和 content 三个核心字段。content 指定支持的媒体类型（如 application/json）及其对应的 Schema。

requestBody:
  description: 创建用户所需的数据
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - username
          - email
        properties:
          username:
            type: string
            minLength: 3
            maxLength: 50
          email:
            type: string
            format: email
          age:
            type: integer
            minimum: 0

  最佳实践： 始终为 requestBody 设置 required: true 或 false，避免歧义。对于 GET 和 DELETE 操作，通常不需要定义请求体；如果确实需要，应在文档中明确说明。

2.5 响应（Response）

响应定义了服务端返回给客户端的数据结构。每个操作必须至少定义一个成功响应（通常为 200、201 或 204），并建议定义常见的错误响应。

响应对象包含 description（必填）和 content（可选）。content 结构与请求体类似，指定媒体类型和 Schema。

HTTP 状态码	含义	典型场景
200 OK	请求成功	GET 获取资源、PUT 更新成功
201 Created	资源创建成功	POST 创建新资源
204 No Content	成功但无返回体	DELETE 删除成功
400 Bad Request	客户端请求错误	参数校验失败
404 Not Found	资源不存在	路径参数指向不存在的资源
500 Internal Server Error	服务端内部错误	未预期的异常

responses:
  '200':
    description: 成功返回用户列表
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/User'
  '400':
    description: 请求参数错误
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
            message:
              type: string

2.6 五要素综合示例

以下是一个完整的 OpenAPI 路径定义，展示了五个核心要素如何协同工作：

paths:
  /orders:
    post:
      operationId: createOrder
      summary: 创建新订单
      parameters:
        - name: X-Idempotency-Key
          in: header
          description: 幂等键，防止重复创建
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - productId
                - quantity
              properties:
                productId:
                  type: integer
                quantity:
                  type: integer
                  minimum: 1
                couponCode:
                  type: string
      responses:
        '201':
          description: 订单创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId:
                    type: integer
                  status:
                    type: string
                    enum: [pending, confirmed]
                  totalPrice:
                    type: number
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 订单已存在（幂等冲突）

实战要点： 在编写接口契约时，建议先确定路径和操作，再定义参数和请求体，最后完善响应。响应定义应覆盖至少一个成功状态码和两个常见错误状态码，确保客户端能够正确处理各种情况。