参数序列化

注意

OAS 3 本指南适用于 OpenAPI 3.0。

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

• style 定义了多个值如何分隔。可能的样式取决于参数位置——路径、查询、Header 或 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。给定路径 /users，查询参数 id 的查询字符串序列化如下

样式	展开	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 发送。

Header 参数

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

样式	展开	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 参数

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，定义如下

paths:
  # /users;id=3;id=4?metadata=true
  /users{id}:
    get:
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: array
            items:
              type: integer
            minItems: 1
          style: matrix
          explode: true
        - in: query
          name: metadata
          schema:
            type: boolean
          # Using the default serialization for query parameters:
          # style=form, explode=false, allowReserved=false
      responses:
        '200':
          description: A list of users

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

/users{;id*}{?metadata}

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

其他序列化方法

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

没有找到您要找的内容？询问社区
发现错误？让我们知道