描述单个操作参数。唯一参数由 名称 和 位置 的组合定义。

4.8.12.1 参数位置

in 字段指定了四个可能的参数位置

• path - 与 路径模板 一起使用，其中参数值实际上是操作 URL 的一部分。这并不包括 API 的主机或基本路径。例如，在 /items/{itemId} 中，路径参数为 itemId。
• query - 附加到 URL 的参数。例如，在 /items?id=### 中，查询参数为 id。
• header - 作为请求的一部分预期的自定义标头。请注意，[RFC7230] 第 22 页 指出标头名称不区分大小写。
• cookie - 用于将特定的 cookie 值传递给 API。

4.8.12.2 固定字段

字段名称	类型	描述
名称	字符串	必需。参数的名称。参数名称区分大小写。- 如果 in 为 "path"，则 name 字段必须对应于 路径 对象中 路径对象 的 路径 字段中出现的模板表达式。有关更多信息，请参阅 路径模板。- 如果 in 为 "header" 且 name 字段为 "Accept"、"Content-Type" 或 "Authorization"，则应忽略参数定义。- 对于所有其他情况，name 对应于 in 属性使用的参数名称。
in	字符串	必需。参数的位置。可能的值为 "query"、"header"、"path" 或 "cookie"。
描述	字符串	参数的简要描述。这可能包含使用示例。[CommonMark 规范] 语法可以用于富文本表示。
必需	布尔值	确定此参数是否为必需。如果 参数位置 为 "path"，则此属性为必需，其值必须为 true。否则，可以包含此属性，其默认值为 false。
已弃用	布尔值	指定参数已弃用，应停止使用。默认值为 false。
允许空值	布尔值	设置传递空值参数的能力。这仅对 query 参数有效，并允许发送具有空值的参数。默认值为 false。如果使用了 style，并且如果行为为 n/a（无法序列化），则应忽略 allowEmptyValue 的值。不建议使用此属性，因为它可能会在以后的修订版中删除。

参数序列化的规则以两种方式之一指定。对于更简单的场景，schema 和 style 可以描述参数的结构和语法。

字段名称	类型	描述
样式	字符串	根据参数值的类型描述参数值将如何序列化。默认值（基于 in 的值）：对于 query - form；对于 path - simple；对于 header - simple；对于 cookie - form。
展开	布尔值	当此值为 true 时，类型为 array 或 object 的参数值会为数组的每个值或映射的键值对生成单独的参数。对于其他类型的参数，此属性无效。当 style 为 form 时，默认值为 true。对于所有其他样式，默认值为 false。
允许保留字符	布尔值	确定参数值应否允许包含 [RFC3986] 第 2.2 节 定义的保留字符 :/?#[]@!$&'()*+,;=，而无需进行百分比编码。此属性仅适用于 in 值为 query 的参数。默认值为 false。
模式	模式对象	定义用于参数的类型的模式。
示例	任何	参数潜在值的示例。如果存在，则示例应与指定的模式和编码属性匹配。example 字段与 examples 字段互斥。此外，如果引用包含示例的 schema，则 example 值应 覆盖模式提供的示例。若要表示 JSON 或 YAML 中无法自然表示的媒体类型的示例，字符串值可以包含示例，并在必要时进行转义。
示例	Map[ string, 示例对象  引用对象]	参数潜在值的示例。每个示例应包含以参数编码中指定的正确格式表示的值。examples 字段与 example 字段互斥。此外，如果引用包含示例的 schema，则 examples 值应 覆盖模式提供的示例。

对于更复杂的场景，content 属性可以定义参数的媒体类型和模式。参数必须包含 schema 属性或 content 属性，但不能同时包含两者。当与 schema 对象一起提供 example 或 examples 时，示例必须遵循参数规定的序列化策略。

字段名称	类型	描述
内容	Map[string, 媒体类型对象]	包含参数表示形式的映射。键是媒体类型，值描述它。映射必须仅包含一个条目。

4.8.12.3 样式值

为了支持序列化简单参数的常用方法，定义了一组 style 值。

样式	类型	in	注释
矩阵	primitive、array、object	路径	[RFC6570] 第 3.2.7 节 定义的路径样式参数
标签	primitive、array、object	路径	[RFC6570] 第 3.2.5 节 定义的标签样式参数
表单	primitive、array、object	query、cookie	[RFC6570] 第 3.2.8 节 定义的表单样式参数。此选项使用 csv（当 explode 为 false 时）或 multi（当 explode 为 true 时）值替换 OpenAPI 2.0 中的 collectionFormat。
简单	数组	path、header	[RFC6570] 第 3.2.2 节 定义的简单样式参数。此选项使用 csv 值替换 OpenAPI 2.0 中的 collectionFormat。
空格分隔	array、object	查询	空格分隔的数组或对象值。此选项替换 OpenAPI 2.0 中等于 ssv 的 collectionFormat。
管道分隔	array、object	查询	管道分隔的数组或对象值。此选项替换 OpenAPI 2.0 中等于 pipes 的 collectionFormat。
深度对象	对象	查询	提供了一种使用表单参数呈现嵌套对象简单的方法。

4.8.12.4 样式示例

假设名为 color 的参数具有以下值之一

   string -> "blue"
   array -> ["blue","black","brown"]
   object -> { "R": 100, "G": 200, "B": 150 }

下表显示了每个值的呈现差异示例。

样式	展开	空	字符串	数组	对象
矩阵	false	;color	;color=blue	;color=blue,black,brown	;color=R,100,G,200,B,150
矩阵	true	;color	;color=blue	;color=blue;color=black;color=brown	;R=100;G=200;B=150
标签	false	.	.blue	.blue.black.brown	.R.100.G.200.B.150
标签	true	.	.blue	.blue.black.brown	.R=100.G=200.B=150
表单	false	color=	color=blue	color=blue,black,brown	color=R,100,G,200,B,150
表单	true	color=	color=blue	color=blue&color=black&color=brown	R=100&G=200&B=150
简单	false	n/a	blue	blue,black,brown	R,100,G,200,B,150
简单	true	n/a	blue	blue,black,brown	R=100,G=200,B=150
空格分隔	false	n/a	n/a	blue%20black%20brown	R%20100%20G%20200%20B%20150
管道分隔	false	n/a	n/a	blue,black,brown	R,100,G,200,B,150
深度对象	true	n/a	n/a	n/a	color[R]=100&color[G]=200&color[B]=150

此对象*可以使用 规范扩展 进行扩展。

4.8.12.5 Parameter 对象示例

具有 64 位整数数组的标头参数

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "integer",
      "format": "int64"
    }
  },
  "style": "simple"
}

name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple

字符串值的路径参数

{
  "name": "username",
  "in": "path",
  "description": "username to fetch",
  "required": true,
  "schema": {
    "type": "string"
  }
}

name: username
in: path
description: username to fetch
required: true
schema:
  type: string

字符串值的可选查询参数，通过重复查询参数允许多个值

{
  "name": "id",
  "in": "query",
  "description": "ID of the object to fetch",
  "required": false,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "style": "form",
  "explode": true
}

name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

自由格式查询参数，允许特定类型的未定义参数

{
  "in": "query",
  "name": "freeForm",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "integer"
    },
  },
  "style": "form"
}

in: query
name: freeForm
schema:
  type: object
  additionalProperties:
    type: integer
style: form

使用 content 定义序列化的复杂参数

{
  "in": "query",
  "name": "coordinates",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "lat",
          "long"
        ],
        "properties": {
          "lat": {
            "type": "number"
          },
          "long": {
            "type": "number"
          }
        }
      }
    }
  }
}

in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number