OAS 3 此页面介绍的是 OpenAPI 3.0。如果您使用 OpenAPI 2.0，请参阅 OpenAPI 2.0 指南。

媒体类型

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

paths:
  /employees:
    get:
      summary: Returns a list of employees.
      responses:
        '200':      # Response
          description: OK
          content:  # Response body
            application/json:  # Media type
              schema:          # Must-have
                type: object   # Data type
                properties: 
                  id:
                    type: integer
                  name:
                    type: string
                  fullTime: 
                    type: boolean
                example:       # Sample data
                    id: 1
                    name: Jessica Right
                    fullTime: true

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

媒体类型名称

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

application/json
application/xml
application/x-www-form-urlencoded
multipart/form-data
text/plain; charset=utf-8
text/html
application/pdf
image/png

application/vnd.mycompany.myapp.v2+json
application/vnd.ms-excel
application/vnd.openstreetmap.data+xml
application/vnd.github-issue.text+json
application/vnd.github.v3.diff
image/vnd.djvu

多种媒体类型

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

paths:
  /employees:
    get:
      summary: Returns a list of employees.
      responses:
        '200':      # Response
          description: OK
          content:  # Response body
            application/json:   # One of media types
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  fullTime: 
                    type: boolean
            application/xml:    # Another media types
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  fullTime: 
                    type: boolean

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

paths:
  /employees:
    get:
      responses:
        '200':      # Response
          description: OK
          content:  # Response body
            application/json:  # Media type
             schema: 
               $ref: '#/components/schemas/Employee'    # Reference to object definition
            application/xml:   # Media type
             schema: 
               $ref: '#/components/schemas/Employee'    # Reference to object definition
components:
  schemas:
    Employee:      # Object definition
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        fullTime: 
          type: boolean

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

paths:
  /info/logo:
    get:
      responses:
        '200':           # Response
          description: OK
          content:       # Response body
            image/*:     # Media type
             schema: 
               type: string
               format: binary

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

  

没有找到您要找的内容？咨询社区
发现错误？告知我们