External Documentation 对象

允许引用外部资源来扩展文档。

External Documentation 对象示例

{
  "description": "Find more info here",
  "url": "https://example.com"
}

description: Find more info here
url: https://example.com

Parameter 对象

描述一个操作参数。

一个参数的唯一性由 name 和 location 的组合来确定。

参数位置

有 4 种可能的参数位置值可用于in字段：

path - 与 Path Templating 一起使用，当参数的值是 URL 操作路径的一部分时可以使用，但是不包含主机地址或基础路径。比如在路径 /items/{itemId} 中，路径参数是 itemId。
query - 追加在 URL 地址之后的参数，比如 /items?id=### 中，查询参数是 id。
header - 请求中使用的自定义请求头，注意在 RFC7230 中规定，请求头的命名是不区分大小写的。
cookie - 用于传递特定的 cookie 值。

固定字段

字段名	类型	描述
name	string	必选。参数的名称。参数名是区分大小写。- 如果 in 的值是 "path"，那么 name 字段的值必须与其关联的 Paths 对象内 path 字段的定义相呼应，查看 Path Templating 了解更多信息。- 如果 in 的值是 "header" 而且 name 字段的值是 "Accept"、"Content-Type" 或 "Authorization" 之一，那么此参数定义应该被忽略。- 除此之外的情况，name 表示 in 属性的名字。
in	string	必选。参数的位置，可能的值有 "query"、"header"、"path" 或 "cookie"。
description	string	对此参数的简要描述，这里可以包含使用示例。CommonMark syntax 可以被用来呈现富文本格式。
required	boolean	标明此参数是否是必选参数。如果参数位置的值是 path，那么这个参数一定是必选的，因此这里的值必须是 true。其他的则视情况而定。此字段的默认值是 false。
deprecated	boolean	标明一个参数是被弃用的而且应该尽快移除对它的使用。
allowEmptyValue	boolean	设置是否允许传递空参数，这只在参数值为 query 时有效，默认值是 false。如果同时指定了 style 属性且值为 n/a（无法被序列化），那么此字段 allowEmptyValue 应该被忽略。

序列化参数的规则有两种。对于简单的场景， schema 和 style 可以用于描述参数的结构和语法。

字段名	类型	描述
style	string	描述根据参数值类型的不同如何序列化参数。默认值为（基于 in 字段的值）：query 对应 form；path 对应 simple; header 对应 simple; cookie 对应 form。
explode	boolean	当这个值为 true 时，参数值类型为 array 或 object 的参数使用数组内的值或对象的键值对生成带分隔符的参数值。对于其他类型的参数，这个字段没有任何影响。当 style 是 form 时，这里的默认值是 true，对于其他 style 值类型，默认值是 false。
allowReserved	boolean	决定此参数的值是否允许不使用%号编码使用定义于 RFC3986 内的保留字符 :/?#[]@!$&'()*+,;=。这个属性仅用于 in 的值是 query 时，此字段的默认值是 false。
schema	Schema 对象 \| Reference 对象	定义适用于此参数的类型结构。
example	Any	不同媒体类型的示例，示例应该符合响应的结构的编码属性。各个 example 之间应该是独立的，而且如果一个引用的 schema 也包含一个示例，那么这里定义的示例应该覆盖 schema 包含的示例。为了展现无法被恰当的用 JSON 或 YAML 格式展现的示例时，可以使用经过必要的编码的字符串值。
examples	Map[ string, Example 对象 \| Reference 对象]	不同媒体类型的示例。每个示例应该包含一个对应于指定编码格式的格式正确的值，这个 examples 映射内包含的对象应该不同于 example 内的值。而且如果一个引用的 schema 也包含一个示例，那么这里定义的示例应该覆盖 schema 包含的示例。

对于更复杂的场景，content 属性可以定义参数的媒体类型和概要。一个参数必须且只能包含 schema 和 content 属性中的一个。当 example 或 examples 字段提供了 schema 对象时，示例必须遵照参数的序列化策略。

字段名	类型	描述
content	Map[`string`, Media Type 对象]	一个定义参数如何呈现的键值对映射。键是媒体类型，值是对应媒体类型的示例数据，此键值对只能包含一组键值对。

样式值

已经定义好了一组style类型用于支持常见的通用的简单参数序列化。

`样式`	`类型`	`in`	描述
matrix	`primitive`, `array`, `object`	`path`	Path
样式的参数，参见 RFC6570
label	`primitive`, `array`, `object`	`path`	Label 样式的参数，参见 RFC6570
form	`primitive`, `array`, `object`	`query`, `cookie`	Form 样式的参数，参见 RFC6570. 此选项替换定义于 OpenAPI 2.0 中`collectionFormat`等于 `csv` (当 `explode`值为 false)或`multi` (当 `explode`值为 true)的情况。
simple	`array`	`path`, `header`	Simple 样式的参数，参见 RFC6570. 此选项替换定义于 OpenAPI 2.0 中 `collectionFormat`等于`csv`的情况。
spaceDelimited	`array`	`query`	空格分隔的数组值。此选项替换定义于 OpenAPI 2.0 中 `collectionFormat` equal to `ssv`的情况。
pipeDelimited	`array`	`query`	管道符的数组值。此选项替换定义于 OpenAPI 2.0 中 `collectionFormat`equal to`pipes`的情况。
deepObject	`object`	`query`	提供一种简单的方法来表示参数中的嵌套对象值.

Style 示例

建设一个参数名为color包含如下之一的值：

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

下面这个表展示了各个不同类型值之间的例子。

`style`	`explode`	`empty`	`string`	`array`	`object`
matrix	false	;color	;color=blue	;color=blue,black,brown	;color=R,100,G,200,B,150
matrix	true	;color	;color=blue	;color=blue;color=black;color=brown	;R=100;G=200;B=150
label	false	.	.blue	.blue.black.brown	.R.100.G.200.B.150
label	true	.	.blue	.blue.black.brown	.R=100.G=200.B=150
form	false	color=	color=blue	color=blue,black,brown	color=R,100,G,200,B,150
form	true	color=	color=blue	color=blue&color=black&color=brown	R=100&G=200&B=150
simple	false	n/a	blue	blue,black,brown	R,100,G,200,B,150
simple	true	n/a	blue	blue,black,brown	R=100,G=200,B=150
spaceDelimited	false	n/a	n/a	blue%20black%20brown	R%20100%20G%20200%20B%20150
pipeDelimited	false	n/a	n/a	blue\| black\| brown	R\|100\|G\|200
deepObject	true	n/a	n/a	n/a	color[R]=100&color[G]=200&color[B]=150

这个对象可能会被规范扩展扩展。

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

External Documentation 对象

External Documentation 对象示例​

Parameter 对象​

参数位置​

固定字段​

样式值​

Style 示例​

Parameter 对象示例​