参数序列化

序列化是指将数据结构或对象状态转换为可以传输并在以后重建的格式。OpenAPI 3.0 支持操作参数（路径、查询、标头和 cookie）中的数组和对象，并允许您指定应如何序列化这些参数。序列化方法由 style 和 explode 关键字定义。

style 定义如何分隔多个值。可能的样式取决于参数位置 – 路径、查询、标头或 cookie。
explode（true/false）指定数组和对象是否应为每个数组项或对象属性生成单独的参数。

OpenAPI 序列化规则基于 RFC 6570 定义的 URI 模板模式的子集。工具实现者可以使用现有的 URI 模板库来处理序列化，如下文所述。

路径参数

路径参数支持以下 style 值

simple – （默认）逗号分隔的值。对应于 {param_name} URI 模板。
label – 点前缀的值，也称为标签扩展。对应于 {.param_name} URI 模板。
matrix – 分号前缀的值，也称为路径样式扩展。对应于 {;param_name} URI 模板。

默认序列化方法是 style: simple 和 explode: false。给定路径 /users/{id}，路径参数 id 的序列化方式如下

样式	展开	URI 模板	原始值 id = 5	数组 id = [3, 4, 5]	对象 id = {“role”: “admin”, “firstName”: “Alex”}
simple *	false *	/users/{id}	/users/5	/users/3,4,5	/users/role,admin,firstName,Alex
simple	true	/users/{id*}	/users/5	/users/3,4,5	/users/role=admin,firstName=Alex
label	false	/users/{.id}	/users/.5	/users/.3,4,5	/users/.role,admin,firstName,Alex
label	true	/users/{.id*}	/users/.5	/users/.3.4.5	/users/.role=admin.firstName=Alex
matrix	false	/users/{;id}	/users/;id=5	/users/;id=3,4,5	/users/;id=role,admin,firstName,Alex
matrix	true	/users/{;id*}	/users/;id=5	/users/;id=3;id=4;id=5	/users/;role=admin;firstName=Alex

默认序列化方法

有时将 label 和 matrix 样式与部分路径参数（如 /users{id}）一起使用，因为参数值会添加前缀。

查询参数

查询参数支持以下 style 值

form – （默认）与号分隔的值，也称为表单样式查询扩展。对应于 {?param_name} URI 模板。
spaceDelimited – 空格分隔的数组值。与 OpenAPI 2.0 中的 collectionFormat: ssv 相同。仅对非展开数组 (explode: false) 有效，也就是说，如果数组是单个参数，则空格会分隔数组值，如 arr=a b c。
pipeDelimited – 管道分隔的数组值。与 OpenAPI 2.0 中的 collectionFormat: pipes 相同。仅对非展开数组 (explode: false) 有效，也就是说，如果数组是单个参数，则管道会分隔数组值，如 arr=a|b|c。
deepObject – 简单的非嵌套对象序列化为 paramName[prop1]=value1&paramName[prop2]=value2&...。嵌套对象和数组的行为未定义。

默认序列化方法是 style: form 和 explode: true。这对应于 OpenAPI 2.0 中的 collectionFormat: multi。给定带有查询参数 id 的路径 /users，查询字符串的序列化方式如下

样式	展开	URI 模板	原始值 id = 5	数组 id = [3, 4, 5]	对象 id = {“role”: “admin”, “firstName”: “Alex”}
form *	true *	/users{?id*}	/users?id=5	/users?id=3&id=4&id=5	/users?role=admin&firstName=Alex
form	false	/users{?id}	/users?id=5	/users?id=3,4,5	/users?id=role,admin,firstName,Alex
spaceDelimited	true	/users{?id*}	不适用	/users?id=3&id=4&id=5	不适用
spaceDelimited	false	不适用	不适用	/users?id=3%204%205	不适用
pipeDelimited	true	/users{?id*}	不适用	/users?id=3&id=4&id=5	不适用
pipeDelimited	false	不适用	不适用	/users?id=3\|4\|5	不适用
deepObject	true	不适用	不适用	不适用	/users?id[role]=admin&id[firstName]=Alex

* 默认序列化方法

此外，allowReserved 关键字指定是否允许将参数值中的保留字符 :/?#[]@!$&'()*+,;= 按原样发送，还是应进行百分比编码。默认情况下，allowReserved 为 false，并且保留字符进行百分比编码。例如，/ 编码为 %2F（或 %2f），因此参数值 quotes/h2g2.txt 将作为 quotes%2Fh2g2.txt 发送。

标头参数

标头参数始终使用 simple 样式，即逗号分隔的值。这对应于 {param_name} URI 模板。可选的 explode 关键字控制对象序列化。给定名为 X-MyHeader 的请求标头，标头值序列化如下

样式	展开	URI 模板	原始值 X-MyHeader = 5	数组 X-MyHeader = [3, 4, 5]	对象 X-MyHeader = {“role”: “admin”, “firstName”: “Alex”}
simple *	false *	{id}	X-MyHeader: 5	X-MyHeader: 3,4,5	X-MyHeader: role,admin,firstName,Alex
simple	true	{id*}	X-MyHeader: 5	X-MyHeader: 3,4,5	X-MyHeader: role=admin,firstName=Alex

默认序列化方法

Cookie 参数始终使用 form 样式。可选的 explode 关键字控制数组和对象序列化。给定名为 id 的 cookie，cookie 值序列化如下

样式	展开	URI 模板	原始值 id = 5	数组 id = [3, 4, 5]	对象 id = {“role”: “admin”, “firstName”: “Alex”}
form *	true *		Cookie: id=5
form	false	id={id}	Cookie: id=5	Cookie: id=3,4,5	Cookie: id=role,admin,firstName,Alex

默认序列化方法

序列化和 RFC 6570

OpenAPI 序列化规则基于 RFC 6570 定义的 URI 模板的子集。工具实现者可以使用现有的 URI 模板库来处理序列化。您需要根据路径和参数定义构造 URI 模板。下表显示了 OpenAPI 关键字如何映射到 URI 模板修饰符。

关键字	URI 模板修饰符
`style: simple`	无
`style: label`	`.` 前缀
`style: matrix`	`;` 前缀
`style: form`	`?` 或 `&` 前缀（取决于参数在查询字符串中的位置）
`style: pipeDelimited`	`?` 或 `&` 前缀（取决于参数在查询字符串中的位置）– 但使用管道符 `\|` 代替逗号 `,` 来连接数组值
`style: spaceDelimited`	`?` 或 `&` 前缀（取决于参数在查询字符串中的位置）– 但使用空格代替逗号 `,` 来连接数组值
`explode: false`	无
`explode: true`	`*` 后缀
`allowReserved: false`	无
`allowReserved: true`	`+` 前缀

例如，考虑路径 /users{id} 和查询参数 metadata，定义如下

1
paths:
2
  # /users;id=3;id=4?metadata=true
3
  /users{id}:
4
    get:
5
      parameters:
6
        - in: path
7
          name: id
8
          required: true
9
          schema:
10
            type: array
11
            items:
12
              type: integer
13
            minItems: 1
14
          style: matrix
15
          explode: true
16
        - in: query
17
          name: metadata
18
          schema:
19
            type: boolean
20
          # Using the default serialization for query parameters:
21
          # style=form, explode=false, allowReserved=false
22
      responses:
23
        '200':
24
          description: A list of users

路径参数 id 使用 matrix 样式和 explode 修饰符，这对应于 {;id*} 模板。查询参数 metadata 使用默认的 form 样式，这对应于 {?metadata} 模板。完整的 URI 模板如下所示：

1
/users{;id*}{?metadata}

客户端应用程序可以使用 URI 模板库来根据此模板和特定的参数值生成请求 URL。

其他序列化方法

style 和 explode 涵盖了最常见的序列化方法，但并非全部。对于更复杂的场景（例如，查询字符串中的 JSON 格式对象），您可以使用 content 关键字并指定定义序列化格式的媒体类型。有关更多信息，请参见 schema vs content。

没有找到您要找的内容？向社区提问
发现错误？请告知我们