3、路径与操作定义：路径模板、HTTP方法映射、operationId、summary、description、parameters、requestBody、responses

在 OpenAPI 规范中，路径（Path）与操作（Operation）是 API 契约的核心骨架。路径定义了资源的访问端点，操作则描述了在该端点上可执行的具体行为。本节将系统拆解路径模板、HTTP 方法映射、操作元数据（operationId、summary、description）以及请求/响应描述（parameters、requestBody、responses）的工程化定义方式。

3.1 路径模板与参数化

路径模板使用花括号 {} 声明动态路径参数，支持正则表达式约束。路径参数必须在 parameters 字段中显式定义，且 in: path 必须配合 required: true。

/api/v2/orders/{orderId}
/api/v2/orders/{orderId}/items/{itemId}
/api/v2/users/{userId}/tickets?status={status}

3.2 HTTP 方法映射与操作对象

每个路径下可定义多个 HTTP 方法（get、post、put、delete、patch、head、options、trace）。每个方法对应一个操作对象（Operation Object），包含完整的请求/响应描述。

3.3 operationId、summary 与 description

这三个字段构成操作的元数据层，直接影响 API 的可读性和工具链的自动化能力。

3.4 parameters：路径、查询、请求头与 Cookie

参数定义支持四种位置（in）：path、query、header、cookie。每个参数必须指定 name、in、schema，路径参数还需 required: true。

parameters:
  - name: orderId
    in: path
    required: true
    schema:
      type: string
      format: uuid
    description: 订单唯一标识
  - name: status
    in: query
    required: false
    schema:
      type: string
      enum: [pending, shipped, delivered, cancelled]
    description: 按订单状态过滤
  - name: X-Request-Id
    in: header
    required: false
    schema:
      type: string
    description: 幂等请求标识，用于去重

3.5 requestBody：请求体描述

适用于 POST、PUT、PATCH 方法。必须指定 content 字段，描述媒体类型和对应的 Schema。可选 required 标记请求体是否必须。

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - userId
          - items
        properties:
          userId:
            type: string
          items:
            type: array
            items:
              type: object
              properties:
                productId:
                  type: string
                quantity:
                  type: integer
                  minimum: 1
    application/xml:
      schema:
        $ref: '#/components/schemas/OrderRequest'

3.6 responses：响应描述

每个操作必须至少定义一个成功响应（通常为 200、201 或 204）。响应对象包含 description 和 content，可定义多个状态码和媒体类型。

responses:
  '201':
    description: 订单创建成功
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/OrderResponse'
  '400':
    description: 请求参数校验失败
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
  '500':
    description: 服务器内部错误
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ServerError'

3.7 完整操作定义示例

以下是一个完整的路径操作定义，整合了路径参数、查询参数、请求体和多状态码响应：

/api/v2/orders/{orderId}:
  get:
    operationId: getOrderById
    summary: 根据订单ID获取订单详情
    description: |
      返回订单的完整信息，包括商品列表、支付状态和物流跟踪号。
      如果订单不存在，返回 404 错误。
    parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: includeItems
        in: query
        required: false
        schema:
          type: boolean
          default: true
    responses:
      '200':
        description: 成功返回订单数据
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      '404':
        description: 订单不存在
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotFoundError'
      '500':
        description: 服务器内部错误
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServerError'