媒体类型

媒体类型是请求或响应正文数据的格式。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 指南。