05 · 参数详解：parameters 四种位置

生活类比：参数就像你填快递单—— path = 收件地址（必须写在地址栏，结构化） query = 备注栏（"如果不在帮我放门口"） header = 邮戳和保密签（隐式信息：寄件方式、加急 / 保价） cookie = 跟你绑定的会员卡号（每次寄都自动带）

1. 四种参数位置

`in` 值	在 HTTP 哪里	典型用途
`path`	URL 里的 `{}` 占位	资源 ID（`/users/{id}`）
`query`	URL `?` 后面的 `key=value`	分页、筛选、排序
`header`	HTTP 请求头	Token、Trace-ID、Accept-Language
`cookie`	Cookie 头	Session、追踪

GET /users/123?page=2&size=20  HTTP/1.1
                                              ← path: id=123
                                              ← query: page=2, size=20
Host: api.example.com
Authorization: Bearer xxx                     ← header
Accept-Language: zh-CN                        ← header
Cookie: sessionId=abc123                      ← cookie

2. 参数对象的字段

yaml

parameters:
  - name: page                 # ① 名字
    in: query                  # ② 位置（path/query/header/cookie）
    description: 页码           # ③ 描述
    required: false            # ④ 是否必填（path 必须 true）
    deprecated: false          # ⑤ 废弃标记
    schema:                    # ⑥ 类型
      type: integer
      minimum: 1
      default: 1
    example: 2                 # ⑦ 单一示例
    examples:                  # ⑧ 多组示例
      first:
        value: 1
        summary: 第一页
      latest:
        value: 99
        summary: 最后一页
    style: form                # ⑨ 序列化风格（数组/对象用）
    explode: true              # ⑩ 是否展开
    allowReserved: false       # ⑪ 是否允许 ?,/, 等保留字符

80% 情况下你只用：name + in + required + schema + description。

3. `path` 参数 · 资源标识

yaml

paths:
  /users/{id}:
    parameters:
      - name: id
        in: path
        required: true              # ★ path 永远 required: true
        description: 用户 ID
        schema:
          type: integer
          minimum: 1
        example: 42

规则：

name 必须跟 URL 里 {} 同名
required 必须 true（OpenAPI 规定）
不能有默认值（path 没办法"省略"）

4. `query` 参数 · 最常用

yaml

paths:
  /users:
    get:
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1, minimum: 1 }
        - name: size
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
        - name: sort
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: q
          in: query
          description: 搜索关键词
          schema: { type: string }

请求示例：

GET /users?page=2&size=20&sort=desc&q=张三

4.1 数组型 query 的 4 种序列化

OpenAPI 规定了 style + explode 组合，控制数组怎么放进 URL：

yaml

- name: tags
  in: query
  schema:
    type: array
    items: { type: string }
  style: form          # 默认
  explode: true        # 默认

style	explode	URL
form	true	`?tags=a&tags=b&tags=c` (默认)
form	false	`?tags=a,b,c`
spaceDelimited	false	`?tags=a%20b%20c`
pipeDelimited	false	`?tags=a\|b\|c`

实际工程：保持默认 form + explode=true 最兼容（绝大多数后端框架都默认按这个解析）。

4.2 对象型 query

yaml

- name: filter
  in: query
  schema:
    type: object
    properties:
      status: { type: string }
      role: { type: string }
  style: deepObject
  explode: true

URL：?filter[status]=active&filter[role]=admin

太复杂了，工程实践推荐：复杂筛选用 POST + body，不要往 query 里硬塞对象。

5. `header` 参数 · 元信息

yaml

parameters:
  - name: X-Trace-Id
    in: header
    description: 链路追踪 ID（前端生成 UUID）
    schema:
      type: string
      example: "trace-abc-123"
  - name: Accept-Language
    in: header
    schema:
      type: string
      enum: [zh-CN, en-US]
      default: zh-CN

⚠️ 不要在 OpenAPI 的 parameters 里描述 Authorization 头！它属于 security（第 7 章），用专门的 securitySchemes 描述更规范。

⚠️ Content-Type、Accept、Authorization 这些标准头不要写在 parameters 里——OpenAPI 规范明确禁止。

6. `cookie` 参数

yaml

parameters:
  - name: tracker
    in: cookie
    schema:
      type: string

实际中 cookie 多用于 session 鉴权，那种情况也归 securitySchemes，很少在 parameters 里直接写 cookie。

7. `schema` 字段类型大全

yaml

schema:
  type: integer | number | string | boolean | array | object | null

7.1 字符串约束

yaml

schema:
  type: string
  minLength: 3
  maxLength: 50
  pattern: '^[a-zA-Z0-9_]+$'      # 正则
  format: email                    # 格式提示
  enum: [admin, user, guest]       # 枚举
  default: user
  example: alice

format 常见值：

format	含义
date	`2026-05-11`
date-time	`2026-05-11T10:00:00Z`
email	邮箱
uuid	UUID
uri	URL
password	密码（UI 用 `<input type=password>`）
binary	二进制（文件上传）
byte	base64 编码
ipv4 / ipv6	IP 地址

7.2 数字约束

yaml

schema:
  type: integer        # 或 number（浮点）
  format: int32        # int32 / int64 / float / double
  minimum: 1
  maximum: 100
  exclusiveMinimum: false
  exclusiveMaximum: false
  multipleOf: 5        # 必须是 5 的倍数
  default: 10

7.3 数组约束

yaml

schema:
  type: array
  items:
    type: string
  minItems: 1
  maxItems: 10
  uniqueItems: true

7.4 枚举

yaml

schema:
  type: string
  enum:
    - draft
    - published
    - archived
  default: draft

UI 会展示成下拉框。

8. 用 `components.parameters` 复用

参数也能扔到 components 里：

yaml

components:
  parameters:
    PageQuery:
      name: page
      in: query
      schema: { type: integer, default: 1, minimum: 1 }
      description: 页码

    SizeQuery:
      name: size
      in: query
      schema: { type: integer, default: 20, maximum: 100 }

    SortQuery:
      name: sort
      in: query
      schema:
        type: string
        enum: [asc, desc]
        default: desc

paths:
  /users:
    get:
      parameters:
        - $ref: '#/components/parameters/PageQuery'
        - $ref: '#/components/parameters/SizeQuery'
        - $ref: '#/components/parameters/SortQuery'

  /products:
    get:
      parameters:
        - $ref: '#/components/parameters/PageQuery'      # 复用！
        - $ref: '#/components/parameters/SizeQuery'

工程经验：分页、排序、过滤这"老三样"必须复用。

9. 实战 · "搜索文章"接口的完整 parameters

yaml

paths:
  /posts/search:
    get:
      summary: 搜索文章
      parameters:
        - $ref: '#/components/parameters/PageQuery'
        - $ref: '#/components/parameters/SizeQuery'

        - name: q
          in: query
          description: 关键词
          schema:
            type: string
            minLength: 1
            maxLength: 100
          example: "JavaScript"

        - name: tags
          in: query
          description: 标签筛选（多选）
          schema:
            type: array
            items: { type: string }
          example: [vue, react]

        - name: status
          in: query
          schema:
            type: string
            enum: [draft, published, archived]
            default: published

        - name: createdAfter
          in: query
          description: 创建时间下界
          schema:
            type: string
            format: date-time
          example: "2024-01-01T00:00:00Z"

        - name: Accept-Language
          in: header
          schema:
            type: string
            enum: [zh-CN, en-US]
            default: zh-CN

        - name: X-Trace-Id
          in: header
          description: 链路追踪
          schema: { type: string }
      responses:
        '200': { description: OK }

10. 常见坑

10.1 `path` 参数没声明

yaml

# ✗ 错：URL 里有 {id}，但没在 parameters 里声明
paths:
  /users/{id}:
    get:
      responses: {...}

Spectral / Swagger 会报错：Path parameter 'id' is not defined。一定要写：

yaml

paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }

10.2 query 参数 required 漏写

yaml

# ✗ 错：query 默认 required: false，前端可能不传
- name: token
  in: query
  schema: { type: string }

# ✓ 对：明确必填
- name: token
  in: query
  required: true
  schema: { type: string }

10.3 描述 `Content-Type` 头

yaml

# ✗ 错：Content-Type 不能写在 parameters
- name: Content-Type
  in: header
  schema: { type: string }

应该用 requestBody.content 表达（第 6 章）。

10.4 enum 大小写

yaml

schema:
  type: string
  enum: [Draft, Published, ARCHIVED]   # 实际后端只接受小写？
  default: draft                        # 默认值不在枚举里！

default 必须在 enum 里，否则有些工具会报警告。

11. 章末面试题速览

path 参数为什么必须 required: true？ → URL 里的 {} 没法"省略"，所以一定要传。
query 数组 ?tags=a&tags=b 和 ?tags=a,b 在 OpenAPI 里怎么表达？ → 通过 style + explode：默认 form + explode=true 是 ?tags=a&tags=b；form + explode=false 是 ?tags=a,b。
Authorization 头要写在 parameters 还是 securitySchemes？ → securitySchemes！parameters 不能描述安全相关的头。

🎬 可视化演示

下方 demo 是一个 "参数 → URL 拼接器"——勾选不同参数，实时看到最终发出的 HTTP 请求是什么样。

→ 打开 05_parameters/demo.html

🎬 可视化演示

演示加载缓慢或样式异常？点此在新标签页打开 ↗

05 · 参数详解：parameters 四种位置 ​

1. 四种参数位置 ​

2. 参数对象的字段 ​

3. path 参数 · 资源标识 ​

4. query 参数 · 最常用 ​

4.1 数组型 query 的 4 种序列化 ​

4.2 对象型 query ​

5. header 参数 · 元信息 ​

6. cookie 参数 ​

7. schema 字段类型大全 ​

7.1 字符串约束 ​

7.2 数字约束 ​

7.3 数组约束 ​

7.4 枚举 ​

8. 用 components.parameters 复用 ​

9. 实战 · "搜索文章"接口的完整 parameters ​

10. 常见坑 ​

10.1 path 参数没声明 ​

10.2 query 参数 required 漏写 ​

10.3 描述 Content-Type 头 ​

10.4 enum 大小写 ​

11. 章末面试题速览 ​

🎬 可视化演示 ​

🎬 可视化演示 ​

05 · 参数详解：parameters 四种位置

1. 四种参数位置

2. 参数对象的字段

3. `path` 参数 · 资源标识

4. `query` 参数 · 最常用

4.1 数组型 query 的 4 种序列化

4.2 对象型 query

5. `header` 参数 · 元信息

6. `cookie` 参数

7. `schema` 字段类型大全

7.1 字符串约束

7.2 数字约束

7.3 数组约束

7.4 枚举

8. 用 `components.parameters` 复用

9. 实战 · "搜索文章"接口的完整 parameters

10. 常见坑

10.1 `path` 参数没声明

10.2 query 参数 required 漏写

10.3 描述 `Content-Type` 头

10.4 enum 大小写

11. 章末面试题速览

🎬 可视化演示

🎬 可视化演示