媒体类型

媒体类型是请求或响应正文数据的格式。Web 服务操作可以接受并返回不同格式的数据，最常见的是 JSON、XML 和图像。您在请求和响应定义中指定媒体类型。以下是响应定义示例：

1
paths:
2
  /employees:
3
    get:
4
      summary: Returns a list of employees.
5
      responses:
6
        "200": # Response
7
          description: OK
8
          content: # Response body
9
            application/json: # Media type
10
              schema: # Must-have
11
                type: object # Data type
12
                properties:
13
                  id:
14
                    type: integer
15
                  name:
16
                    type: string
17
                  fullTime:
18
                    type: boolean
19
                example: # Sample data
20
                  id: 1
21
                  name: Jessica Right
22
                  fullTime: true

在 responses 下，我们有单个响应的定义。如您所见，每个响应都由其代码定义（在我们的示例中是 '200'）。代码下方的关键词 content 对应于响应体。一个或多个媒体类型作为此 content 关键词的子关键词。每个媒体类型都包含一个 schema，定义消息体的数据类型，并且可选地包含一个或多个示例。有关定义正文数据的更多信息，请参阅定义请求体和定义响应。

媒体类型名称

content 字段下所列的媒体类型应符合 RFC 6838。例如，您可以使用标准类型或供应商特定类型（由 .vnd 指示）–

1
application/json
2
application/xml
3
application/x-www-form-urlencoded
4
multipart/form-data
5
text/plain; charset=utf-8
6
text/html
7
application/pdf
8
image/png

1
application/vnd.mycompany.myapp.v2+json
2
application/vnd.ms-excel
3
application/vnd.openstreetmap.data+xml
4
application/vnd.github-issue.text+json
5
application/vnd.github.v3.diff
6
image/vnd.djvu

多种媒体类型

您可能需要指定多种媒体类型

1
paths:
2
  /employees:
3
    get:
4
      summary: Returns a list of employees.
5
      responses:
6
        "200": # Response
7
          description: OK
8
          content: # Response body
9
            application/json: # One of media types
10
              schema:
11
                type: object
12
                properties:
13
                  id:
14
                    type: integer
15
                  name:
16
                    type: string
17
                  fullTime:
18
                    type: boolean
19
            application/xml: # Another media types
20
              schema:
21
                type: object
22
                properties:
23
                  id:
24
                    type: integer
25
                  name:
26
                    type: string
27
                  fullTime:
28
                    type: boolean

要对多种媒体类型使用相同的数据格式，请在您的规范的 components 部分定义一个自定义对象，然后在每种媒体类型中引用此对象。

1
paths:
2
  /employees:
3
    get:
4
      responses:
5
        "200": # Response
6
          description: OK
7
          content: # Response body
8
            application/json: # Media type
9
              schema:
10
                $ref: "#/components/schemas/Employee" # Reference to object definition
11
            application/xml: # Media type
12
              schema:
13
                $ref: "#/components/schemas/Employee" # Reference to object definition
14
components:
15
  schemas:
16
    Employee: # Object definition
17
      type: object
18
      properties:
19
        id:
20
          type: integer
21
        name:
22
          type: string
23
        fullTime:
24
          type: boolean

要为多种媒体类型定义相同的格式，您还可以使用通配符，例如 */*、application/*、image/* 或其他。

1
paths:
2
  /info/logo:
3
    get:
4
      responses:
5
        "200": # Response
6
          description: OK
7
          content: # Response body
8
            image/*: # Media type
9
              schema:
10
                type: string
11
                format: binary

您用作媒体类型的值（在我们的示例中是 image/*）与您在 HTTP 请求和响应的 Accept 或 Content-Type 标头中看到的值非常相似。请勿混淆通配符和 Accept 或 Content-Type 标头的实际值。例如，响应体的 image/* 通配符表示服务器将对所有符合该通配符的响应使用相同的数据结构。这并不意味着字符串 image/* 将在 Content-Type 标头中指定。Content-Type 标头很可能将是 image/png、image/jpeg 或其他类似值。

_没有找到您要找的内容？咨询社区发现错误？告诉我们_OAS 3 本页介绍 OpenAPI 3.0。如果您使用 OpenAPI 2.0，请参阅 OpenAPI 2.0 指南。