媒體類型

媒體類型是請求或回應主體資料的格式。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/* 預留位置表示伺服器將對所有符合預留位置的回應使用相同的資料結構。這並不表示 Content-Type 標頭中將指定字串 *image/*。 Content-Type 標頭很可能會具有 *image/png*、*image/jpeg* 或其他類似的值。

_找不到您要找的內容嗎？詢問社群發現錯誤？請告訴我們_OAS 3 此頁面是關於 OpenAPI 3.0。如果您使用 OpenAPI 2.0，請參閱 OpenAPI 2.0 指南。