每个媒体类型对象都为其键标识的媒体类型提供模式和示例。

4.8.14.1 固定字段

字段名称	类型	描述
模式	模式对象	定义请求、响应或参数内容的模式。
示例	任何	媒体类型的示例。示例对象应该采用媒体类型指定的正确格式。example 字段与 examples 字段互斥。此外，如果引用包含示例的 schema，则 example 值必须 覆盖 schema 提供的示例。
examples	Map[ string, 示例对象  引用对象]	媒体类型的示例。每个示例对象应该匹配媒体类型，如果存在，则匹配指定的 schema。examples 字段与 example 字段互斥。此外，如果引用包含示例的 schema，则 examples 值必须 覆盖 schema 提供的示例。
encoding	Map[string, 编码对象]	属性名称与其编码信息之间的映射。键（即属性名称）必须在 schema 中作为属性存在。编码对象必须仅在媒体类型为 multipart 或 application/x-www-form-urlencoded 时应用于 requestBody 对象。

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

*4.8.14.2 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"

4.8.14.3 文件上传注意事项

与 2.0 规范相反，OpenAPI 中的文件输入/输出内容使用与任何其他 schema 类型相同的语义进行描述。与 3.0 规范相反，format 关键字对 schema 的内容编码没有影响。JSON Schema 提供了一个 contentEncoding 关键字，可用于指定 schema 的 Content-Encoding。contentEncoding 关键字支持 [RFC4648] 中定义的所有编码，包括“base64”和“base64url”，以及 [RFC2045] 第 6.7 节 中的“quoted-printable”。contentEncoding 关键字指定的编码独立于请求或响应中的 Content-Type 标头或多部分正文的元数据中指定的编码 - 当两者都存在时，contentEncoding 中指定的编码将首先应用，然后应用 Content-Type 标头中指定的编码。

JSON Schema 还提供了一个 contentMediaType 关键字。但是，当媒体类型已由媒体类型对象的键或 编码对象 的 contentType 字段指定时，如果存在，则必须忽略 contentMediaType 关键字。示例以二进制 (octet-stream) 传输的内容可以省略 schema

# a PNG image as a binary file:
content:
    image/png: {}

# an arbitrary binary file:
content:
    application/octet-stream: {}

使用 base64 编码传输的二进制内容

content:
    image/png:
        schema:
            type: string
            contentMediaType: image/png
            contentEncoding: base64

请注意，Content-Type 保持为 image/png，描述有效负载的语义。JSON Schema 的 type 和 contentEncoding 字段说明有效负载作为文本传输。JSON Schema 的 contentMediaType 在技术上是冗余的，但可由可能不知道 OpenAPI 上下文的 JSON Schema 工具使用。这些示例适用于文件上传的输入有效负载或响应有效负载。用于在 POST 操作中提交文件的 requestBody 可能如下例所示

requestBody:
  content:
    application/octet-stream: {}

此外，可以指定特定的媒体类型

# multiple, specific media types may be specified:
requestBody:
  content:
    # a binary file of type png or jpeg
    image/jpeg: {}
    image/png: {}

要上传多个文件，必须使用 multipart 媒体类型

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

如以下 multipart/form-data 部分所示，items 的空 schema 表示 application/octet-stream 的媒体类型。

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

要使用 [RFC1866] 通过表单 URL 编码提交内容，可以使用以下定义

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 内容类型中传递复杂对象时，此类属性的默认序列化策略在 编码对象 的 style 属性中描述为 form。

*4.8.14.5 multipart 内容的特殊注意事项

将 multipart/form-data 用作将请求正文传输到操作时的 Content-Type 非常常见。与 2.0 相比，需要使用 schema 来定义使用 multipart 内容时操作的输入参数。这支持复杂结构以及对多个文件上传的支持机制。 在 multipart/form-data 请求正文中，每个 schema 属性或 schema 数组属性的每个元素都在有效负载中占据一部分，并具有 [RFC7578] 定义的内部标头。可以在关联的 编码对象 中指定 multipart/form-data 请求正文的每个属性的序列化策略。 在传递 multipart 类型时，可以使用边界来分隔正在传输的内容的部分 - 因此，为 multipart 定义了以下默认 Content-Type

• 如果属性是原始类型或原始值的数组，则默认的 Content-Type 为 text/plain
• 如果属性是复杂类型或复杂值的数组，则默认的 Content-Type 为 application/json
• 如果属性是带 contentEncoding 的 type: string，则默认的 Content-Type 为 application/octet-stream

根据 JSON Schema 规范，如果不存在 contentEncoding，则 contentMediaType 将被视为存在 contentEncoding: identity。虽然这对于将 text/html 等文本文档嵌入到 JSON 字符串中很有用，但对于 multipart/form-data 部分则没有用，因为它只会导致文档被视为 text/plain 而不是其实际媒体类型。如果不需要 contentEncoding，请使用不带 contentMediaType 的编码对象。

示例

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:
            # Content-Type for application-level encoded resource is `text/plain`
            type: string
            contentMediaType: image/png
            contentEncoding: base64
          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: object
              $ref: '#/components/schemas/Address'

引入了 encoding 属性，使您可以控制 multipart 请求正文部分的序列化。此属性仅适用于 multipart 和 application/x-www-form-urlencoded 请求正文。