4. 参数详解：路径参数、查询参数、请求头参数、Cookie参数的定义方式、必需性与默认值、参数序列化规则

在OpenAPI 3.0规范中，API参数是接口契约的核心组成部分。本章将系统讲解四种常见参数类型（路径参数、查询参数、请求头参数、Cookie参数）的完整定义方式，包括必需性控制、默认值设置以及关键的序列化规则。理解这些细节是构建可读、可测试、可自动生成客户端代码的API规范的基础。

4.1 参数定义的核心结构

所有参数在OpenAPI规范中共享一个统一的描述结构，通过 in 字段区分参数类型。以下是参数对象的通用字段表：

4.2 四种参数类型的定义方式

4.2.1 路径参数 (Path Parameters)

路径参数嵌入在URL路径模板中，用花括号 {} 标识。它们用于标识具体资源，如用户ID、订单号等。

paths:
  /users/{userId}/orders/{orderId}:
    get:
      parameters:
        - name: userId
          in: path
          required: true
          description: 用户唯一标识
          schema:
            type: integer
            format: int64
            minimum: 1
        - name: orderId
          in: path
          required: true
          description: 订单唯一标识
          schema:
            type: string
            pattern: '^ORD-\d{8}$'
      responses:
        '200':
          description: 订单详情

4.2.2 查询参数 (Query Parameters)

查询参数附加在URL的 ? 之后，用于过滤、排序、分页等非资源标识的场景。它们通常不是必需的。

parameters:
  - name: page
    in: query
    required: false
    description: 页码，从1开始
    schema:
      type: integer
      default: 1
      minimum: 1
  - name: limit
    in: query
    required: false
    description: 每页条数
    schema:
      type: integer
      default: 20
      maximum: 100
  - name: status
    in: query
    required: false
    description: 按状态过滤
    schema:
      type: string
      enum: [active, paused, completed, cancelled]

4.2.3 请求头参数 (Header Parameters)

请求头参数携带在HTTP头部，常用于认证令牌、内容协商、请求追踪等元数据。注意：Accept、Content-Type、Authorization 等标准头通常不在 parameters 中定义，而是使用OpenAPI的专用字段。

parameters:
  - name: X-Request-Id
    in: header
    required: false
    description: 请求追踪ID，用于分布式链路追踪
    schema:
      type: string
      format: uuid
  - name: X-API-Version
    in: header
    required: true
    description: API版本号
    schema:
      type: string
      pattern: '^\d+\.\d+$'
      example: "1.2"

4.2.4 Cookie参数 (Cookie Parameters)

Cookie参数从HTTP Cookie头中提取。与请求头参数不同，Cookie参数专门用于会话标识、用户偏好等持久化在客户端的键值对。

parameters:
  - name: session_id
    in: cookie
    required: true
    description: 用户会话标识
    schema:
      type: string
      format: uuid
  - name: preferred_lang
    in: cookie
    required: false
    description: 用户偏好语言
    schema:
      type: string
      default: "zh-CN"
      enum: [zh-CN, en-US, ja-JP]

4.3 必需性与默认值

必需性（required）和默认值（default）是参数定义中两个容易混淆但又紧密相关的概念：

4.4 参数序列化规则

序列化规则决定了当参数是数组或对象时，如何在URL、请求头或Cookie中编码。这是OpenAPI规范中最容易被忽视但影响客户端代码生成质量的部分。

4.4.1 style 与 explode 的交互

每个参数位置都有默认的 style 值，explode 控制是否将对象/数组展开为独立键值对：

4.4.2 常见序列化示例

假设有一个数组参数 tags，值为 ["java", "openapi", "kafka"]，不同序列化方式的结果如下：

4.4.3 对象参数的序列化

对于对象参数，explode 的影响更为显著。以 filter 对象 {"type": "book", "price": 29.9} 为例：

# form + explode: true (query参数默认)
filter[type]=book&filter[price]=29.9

# form + explode: false
filter=type,book,price,29.9

# deepObject (仅query支持)
filter[type]=book&filter[price]=29.9

4.5 参数定义完整示例

以下是一个综合了四种参数类型的OpenAPI片段，展示了一个带分页、过滤、认证和会话追踪的订单查询接口：

paths:
  /api/v1/orders:
    get:
      operationId: listOrders
      parameters:
        # 查询参数 - 分页
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
        # 查询参数 - 过滤（数组，form+explode）
        - name: status
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum: [pending, confirmed, shipped, delivered]
          style: form
          explode: true
        # 请求头参数 - 认证令牌
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            pattern: '^Bearer\s.+'
          description: Bearer令牌
        # 请求头参数 - 请求追踪
        - name: X-Trace-Id
          in: header
          required: false
          schema:
            type: string
            format: uuid
        # Cookie参数 - 会话
        - name: session_token
          in: cookie
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 订单列表