メディアタイプ

メディアタイプは、リクエストまたはレスポンスボディデータの形式です。ウェブサービス操作は、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 はレスポンスボディに対応します。1 つまたは複数のメディアタイプがこの content キーワードの子キーワードとして記述されます。各メディアタイプには、メッセージボディのデータタイプを定義する schema と、オプションで 1 つまたは複数の例が含まれます。ボディデータの定義に関する詳細については、リクエストボディの定義とレスポンスの定義を参照してください。

メディアタイプ名

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 ガイドを参照してください。