Media Type 对象

每种媒体类型对象都有相应的结构和示例来描述它。

固定字段

字段名	类型	描述

schema	Schema 对象 \| Reference 对象	定义此媒体类型的结构。
example	Any	媒体类型的示例。示例对象应该符合此媒体类型的格式，这里指定的`example`对象 object is mutually exclusive of the `examples` object. 而且如果引用的`schema`也包含示例，在这里指定的`example` 值将会覆盖`schema`提供的示例。
examples	Map[ `string`, Example 对象 \| Reference 对象]媒体类型的示例，每个媒体对象的值都应该匹配它对应的媒体类型的格式。 The `examples` object is mutually exclusive of the `example` object. 而且如果引用的`schema`也包含示例，在这里指定的`example`值将会覆盖`schema`提供的示例。
encoding	Map[`string`, Encoding 对象]	属性名与编码信息的映射。每个属性名必须存在于`schema`属性的 key 中，当媒体类型等于`multipart` 或`application/x-www-form-urlencoded`时，编码对象信息仅适用于`requestBody`。

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

Media Type 示例

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat": {
        "summary": "An example of a cat",
        "value": {
          "name": "Fluffy",
          "petType": "Cat",
          "color": "White",
          "gender": "male",
          "breed": "Persian"
        }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value": {
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        },
        "frog": {
          "$ref": "#/components/examples/frog-example"
        }
      }
    }
  }
}

application/json:
  schema:
    $ref: '#/components/schemas/Pet'
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: '#/components/examples/frog-example'

对文件上传的考虑

相对于 2.0 的规范，file内容的上传与下载在开放 API 规范与其他类型一样使用相同的语法来描述。特别的是:

# content transferred with base64 encoding
schema:
  type: string
  format: base64

# content transferred in binary (octet-stream):
schema:
  type: string
  format: binary

这些示例同时适用于文件上传和下载。

一个使用POST操作提交文件的requestBody看起来像下面这样：

requestBody:
  content:
    application/octet-stream:
      # any media type is accepted, functionally equivalent to `*/*`
      schema:
        # a binary file of any type
        type: string
        format: binary

此外，可以指定明确的媒体类型：

# multiple, specific media types may be specified:
requestBody:
  content:
    # a binary file of type png or jpeg
    'image/jpeg':
      schema:
        type: string
        format: binary
    'image/png':
      schema:
        type: string
        format: binary

为了同时上传多个文件，必须指定multipart媒体类型：

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items:
              type: string
              format: binary

x-www-form-urlencoded 请求体的支持

可以使用下面定义的格式来提交 form url 编码RFC1866的内容：

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # complex types are stringified to support RFC 1866
            type: object
            properties: { }

在这个示例中，在内容被传送到服务器之前，requestBody中的内容必须使用RFC1866 中定义的方式字符串化。此外address字段的复杂对象将会被字符串化。

当使用application/x-www-form-urlencoded格式传送复杂对象时，默认的序列化策略在Encoding 对象 的style 属性中定义为form.

对`multipart`内容的特别思考

使用multipart/form-data作为Content-Type来传送请求体是很常见的做法。相对于 2.0 版本的规范，当定义multipart 内容的输入参数时必须指定schema属性。这不但支持复杂的结构而且支持多文件上传机制。

当使用multipart类型是，可以使用 boundaries 来分隔传送的内容，因此multipart定义了以下默认的Content-Type：

如果属性是一个原始值或者是一个原始值的数组，那么默认的 Content-Type 是 text/plain
如果属性是复杂对象或者复杂对象的数组，那么默认的 Content-Type 是application/json
如果属性是type: string与format: binary或format: base64(也就是文件对象)的组合，那么默认的 Content-Type 是 application/octet-stream

示例:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # default Content-Type for objects is `application/json`
            type: object
            properties: { }
          profileImage:
            # default Content-Type for string/binary is `application/octet-stream`
            type: string
            format: binary
          children:
            # default Content-Type for arrays is based on the `inner` type (text/plain here)
            type: array
            items:
              type: string
          addresses:
            # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
            type: array
            items:
              type: '#/components/schemas/Address'

这里介绍一下用来控制序列化multipart请求体的encoding属性，这个属性只适用于multipart 和application/x-www-form-urlencoded类型的请求体。

Encoding 对象

一个编码定义仅适用于一个结构属性。

固定字段

字段名	类型	描述
contentType	`string`	对具体属性的 Content-Type 的编码。默认值取决于属性的类型：`application/octet-stream`编码适用于`binary`格式的`string`；`text/plain` 适用于其他原始值；`application/json`适用于`object`；对于`array` 值类型的默认值取决于数组内元素的类型，默认值可以是明确的媒体类型(比如`application/json`), 或者通配符类型的媒体类型( 比如`image/*`), 又或者是用分号分隔的两种媒体类型。
headers	Map[`string`, Header 对象 \| Reference 对象]	提供附加信息的请求头键值对映射。比如`Content-Disposition`、`Content-Type` 各自描述了不同的信息而且在这里将会被忽略，如果请求体的媒体类型不是`multipart`，这个属性将会被忽略。
style	`string`	描述一个属性根据它的类型将会被如何序列化。查看Parameter 对象的`style` 属性可以得到更多详细信息。这个属性的行为与`query` 参数相同，包括默认值的定义。如果请求体的媒体类型不是`application/x-www-form-urlencoded`，这个属性将会被忽略。
explode	`boolean`	当这个值为 true 时，类型为 `array` 或 `object` 的属性值会为数组的每个元素或对象的每个键值对分开生成参数。这个属性对其他数据类型没有影响。当`style` 为`form`时，这个属性的默认值是`true`，对于其他的`style`类型，这个属性的默认值是`false` 。这个属性会被忽略如果请求体的媒体类型不是`application/x-www-form-urlencoded`。
allowReserved	`boolean`	决定此参数的值是否允许不使用%号编码使用定义于 RFC3986内的保留字符 `:/?#[]@!$&'()*+,;=`。这个属性仅用于`in`的值是`query`时，此字段的默认值是`false`。这个属性会被忽略如果请求体的媒体类型不是`application/x-www-form-urlencoded`。

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

Encoding 对象示例

requestBody:
  content:
    multipart/mixed:
      schema:
        type: object
        properties:
          id:
            # default is text/plain
            type: string
            format: uuid
          address:
            # default is application/json
            type: object
            properties: { }
          historyMetadata:
            # need to declare XML format!
            description: metadata in XML format
            type: object
            properties: { }
          profileImage:
            # default is application/octet-stream, need to declare an image type only!
            type: string
            format: binary
      encoding:
        historyMetadata:
          # require XML Content-Type in utf-8 encoding
          contentType: application/xml; charset=utf-8
        profileImage:
          # only accept png/jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

Responses 对象

描述一个操作可能发生的响应的响应码与响应包含的响应体的对象。

一份 API 文档不必包含所有可能响应码，因为有些状态码无法提前预知。尽管如此，一份文档还是应当包含所有成功的响应和任何已知的错误响应。

default字段可以用来标记一个响应适用于其他未被规范明确定义的 HTTP 响应码的默认响应。

一个Responses 对象必须至少包含一个响应码，而且是成功的响应。

固定字段

字段名	类型	描述
default	Response 对象 \| Reference 对象	用于描述未被明确声明的 HTTP 响应码的响应的文档。使用这个字段来覆盖未声明的响应。一个 Reference 对象可以链接定义于 OpenAPI 对象 components/responses 区域的响应对象。

模式字段

字段名模式	类型	描述
HTTP Status Code	Response 对象 \| Reference 对象	任何 HTTP status code 都可以被用作属性名，但是每一个状态码只能使用一次，用于描述此状态码的响应。一个 Reference 对象可以链接定义于 OpenAPI 对象 components/responses 区域的响应对象。这个字段名必须包含在双引号中 (例如 "200") 以兼容 JSON 和 YAML。这个字段可以包含大写的通配字符`X`来定义响应码的范围。例如，`2XX` 代表所有位于 `[200-299]` 范围内的响应码。只允许使用以下范围定义：`1XX`, `2XX`, `3XX`, `4XX`, 和 `5XX`。如果同时包含范围定义与明确定义的响应，那么明确定义的响应有更高的优先级。

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

Responses 对象示例

一个代表成功操作的 200 响应和一个代表其他操作状态的默认响应（暗示是一个错误）：

{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}

'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'

Media Type 对象

固定字段​

Media Type 示例​

对文件上传的考虑​

x-www-form-urlencoded 请求体的支持​

对multipart内容的特别思考​

Encoding 对象​

固定字段​

Encoding 对象示例​

Responses 对象​

固定字段​

模式字段​

Responses 对象示例​

固定字段

Media Type 示例

对文件上传的考虑

x-www-form-urlencoded 请求体的支持

对`multipart`内容的特别思考

Encoding 对象

固定字段

Encoding 对象示例

Responses 对象

固定字段

模式字段

Responses 对象示例