リクエストボディの記述

リクエストボディは通常、「作成」および「更新」操作 (POST、PUT、PATCH) で使用されます。たとえば、POST または PUT を使用してリソースを作成する場合、リクエストボディには通常、作成されるリソースの表現が含まれます。OpenAPI 3.0 では、requestBody キーワードを使用してリクエストボディを記述します。

OpenAPI 2.0 との違い

以前に OpenAPI 2.0 を使用したことがある場合は、OpenAPI 3.0 の使用を開始するのに役立つ変更の概要を次に示します。

ボディとフォームパラメータは requestBody に置き換えられました。
操作は、フォームデータと JSON などの他のメディアタイプの両方を消費できるようになりました。
consumes 配列は、メディアタイプをそのスキーマにマップする requestBody.content マップに置き換えられました。
スキーマはメディアタイプによって異なる場合があります。
anyOf と oneOf を使用して、代替スキーマを指定できます。
フォームデータにはオブジェクトを含めることができ、オブジェクトと配列のシリアル化戦略を指定できます。
RFC 7231 に従って定義されたセマンティクスがないため、GET、DELETE、HEAD はリクエストボディを持つことができなくなりました。

requestBody、content、メディアタイプ

OpenAPI 2.0 ではリクエストボディが body および formData パラメータを使用して定義されていたのに対し、OpenAPI 3.0 では requestBody キーワードを使用してペイロードをパラメータ (クエリ文字列など) と区別します。requestBody は、JSON、XML、フォームデータ、プレーンテキストなどのさまざまなメディアタイプを消費し、異なるメディアタイプに異なるスキーマを使用できるという点で、より柔軟です。requestBody は、content オブジェクト、オプションの Markdown 形式の description、およびオプションの required フラグ (デフォルトは false) で構成されます。content は、操作によって消費されるメディアタイプ (例: application/json) をリストし、各メディアタイプの schema を指定します。リクエストボディはデフォルトでオプションです。ボディを必須としてマークするには、required: true を使用します。

1
paths:
2
  /pets:
3
    post:
4
      summary: Add a new pet
5

6
      requestBody:
7
        description: Optional description in *Markdown*
8
        required: true
9
        content:
10
          application/json:
11
            schema:
12
              $ref: "#/components/schemas/Pet"
13
          application/xml:
14
            schema:
15
              $ref: "#/components/schemas/Pet"
16
          application/x-www-form-urlencoded:
17
            schema:
18
              $ref: "#/components/schemas/PetForm"
19
          text/plain:
20
            schema:
21
              type: string
22

23
      responses:
24
        "201":
25
          description: Created

content はワイルドカードメディアタイプを許可します。たとえば、image/* はすべての画像タイプを表し、*/* はすべてのタイプを表し、機能的には application/octet-stream と同等です。仕様を解釈する際には、特定のメディアタイプがワイルドカードメディアタイプよりも優先されます。たとえば、image/png > image/* > */* となります。

1
paths:
2
  /avatar:
3
    put:
4
      summary: Upload an avatar
5
      requestBody:
6
        content:
7
          image/*: # Can be image/png, image/svg, image/gif, etc.
8
            schema:
9
              type: string
10
              format: binary

anyOf, oneOf

OpenAPI 3.0 は anyOf と oneOf をサポートしているため、リクエストボディに代替スキーマを指定できます。

1
requestBody:
2
  description: A JSON object containing pet information
3
  content:
4
    application/json:
5
      schema:
6
        oneOf:
7
          - $ref: "#/components/schemas/Cat"
8
          - $ref: "#/components/schemas/Dog"
9
          - $ref: "#/components/schemas/Hamster"

ファイルアップロード

ファイルアップロードの記述方法については、ファイルアップロードとマルチパートリクエストを参照してください。

リクエストボディの例

リクエストボディには example または複数の examples を含めることができます。example と examples は requestBody.content.<media-type> オブジェクトのプロパティです。これらが指定された場合、これらの例はスキーマによって提供される例を上書きします。これは、たとえば、リクエストとレスポンスが同じスキーマを使用するが、異なる例を使用したい場合に便利です。example は単一のインライン例を許可します。

1
requestBody:
2
  content:
3
    application/json:
4
      schema:
5
        $ref: "#/components/schemas/Pet"
6
      example:
7
        name: Fluffy
8
        petType: dog

examples (複数形) はより柔軟です。インライン例、$ref 参照、またはペイロード例を含む外部 URL を指定できます。各例には、ドキュメンテーション目的でオプションの summary と description を含めることもできます。

1
requestBody:
2
  content:
3
    application/json:
4
      schema:
5
        $ref: '#/components/schemas/Pet'
6
      examples:
7

8
        dog:  # <--- example name
9
          summary: An example of a dog
10
          value:
11
            # vv Actual payload goes here vv
12
            name: Fluffy
13
            petType: dog
14

15
        cat:  # <--- example name
16
          summary: An example of a cat
17
          externalValue: http://api.example.com/examples/cat.json   # cat.json contains {"name": "Tiger", "petType": "cat"}
18

19
        hamster:  # <--- example name
20
          $ref: '#/components/examples/hamster'
21

22
  components:
23
    examples:
24
      hamster:  # <--- example name
25
        summary: An example of a hamster
26
        value:
27
          # vv Actual payload goes here vv
28
          name: Ginger
29
          petType: hamster

詳細については、例の追加を参照してください。

再利用可能なボディ

リクエストボディの定義をグローバルな components.requestBodies セクションに置き、他の場所で $ref 参照することができます。これは、複数の操作が同じリクエストボディを持つ場合に便利です。この方法で同じ定義を簡単に再利用できます。

1
paths:
2
  /pets:
3
    post:
4
      summary: Add a new pet
5
      requestBody:
6
        $ref: '#/components/requestBodies/PetBody'
7

8
  /pets/{petId}
9
    put:
10
      summary: Update a pet
11
      parameters: [ ... ]
12
      requestBody:
13
        $ref: '#/components/requestBodies/PetBody'
14

15
components:
16
  requestBodies:
17
    PetBody:
18
      description: A JSON object containing pet information
19
      required: true
20
      content:
21
        application/json:
22
          schema:
23
            $ref: '#/components/schemas/Pet'

フォームデータ

「フォームデータ」という用語は、HTML フォームの送信によく使用されるメディアタイプ application/x-www-form-urlencoded と multipart/form-data に使用されます。

application/x-www-form-urlencoded は、単純な ASCII テキストデータを key=value ペアとして送信するために使用されます。ペイロード形式はクエリパラメータに似ています。
multipart/form-data は、バイナリデータと複数のメディアタイプを単一のメッセージで送信できます (例: 画像と JSON)。各フォームフィールドは、内部 HTTP ヘッダーを持つペイロード内の独自のセクションを持っています。multipart リクエストは通常、ファイルアップロードに使用されます。

フォームデータを説明するために、HTML の POST フォームを考えてみましょう。

1
<form action="http://example.com/survey" method="post">
2
  <input type="text" name="name" />
3
  <input type="number" name="fav_number" />
4
  <input type="submit" />
5
</form>

このフォームは、フォームのエンドポイントにデータを POST します。

1
POST /survey HTTP/1.1
2
Host: example.com
3
Content-Type: application/x-www-form-urlencoded
4
Content-Length: 28
5

6
name=Amy+Smith&fav_number=42

OpenAPI 3.0 では、フォームデータは type: object スキーマを使用してモデル化され、オブジェクトプロパティがフォームフィールドを表します。

1
paths:
2
  /survey:
3
    post:
4
      requestBody:
5
        required: true
6
        content:
7
          application/x-www-form-urlencoded:
8
            schema:
9
              type: object
10
              properties:
11
                name: # <!--- form field name
12
                  type: string
13
                fav_number: # <!--- form field name
14
                  type: integer
15
              required:
16
                - name
17
                - email

フォームフィールドには、プリミティブ値、配列、およびオブジェクトを含めることができます。デフォルトでは、配列は array_name=value1&array_name=value2 として、オブジェクトは prop1=value1&prop=value2 としてシリアル化されますが、OpenAPI 3.0 仕様で定義されている他のシリアル化戦略を使用することもできます。シリアル化戦略は、encoding セクションで次のように指定されます。

1
requestBody:
2
  content:
3
    application/x-www-form-urlencoded:
4
      schema:
5
        type: object
6
        properties:
7
          color:
8
            type: array
9
            items:
10
              type: string
11
      encoding:
12
        color: # color=red,green,blue
13
          style: form
14
          explode: false

デフォルトでは、application/x-www-form-urlencoded ボディ内のフォームフィールド値にある予約文字 :/?#[]@!$&'()*+,;= は、送信時にパーセントエンコードされます。これらの文字をそのまま送信するには、次のように allowReserved キーワードを使用します。

1
requestBody:
2
  content:
3
    application/x-www-form-urlencoded:
4
      schema:
5
        type: object
6
        properties:
7
          foo:
8
            type: string
9
          bar:
10
            type: string
11
          baz:
12
            type: string
13
      encoding:
14
        # Don't percent-encode reserved characters in the values of "bar" and "baz" fields
15
        bar:
16
          allowReserved: true
17
        baz:
18
          allowReserved: true

任意の key=value ペアは、自由形式のスキーマを使用してモデル化できます。

1
requestBody:
2
  content:
3
    application/x-www-form-urlencoded:
4
      schema:
5
        type: object
6
        additionalProperties: true # this line is optional

フォームデータにおける複雑なシリアル化

style と explode キーワードで提供されるシリアル化ルールは、プリミティブの配列とプリミティブプロパティを持つオブジェクトに対してのみ定義された動作を持ちます。ネストされた配列やフォームデータ内の JSON などのより複雑なシナリオでは、複雑なフィールドの値をエンコードするためのメディアタイプを指定するために contentType キーワードを使用する必要があります。例として、Slack の着信 Webhook を考えてみましょう。メッセージは JSON として直接送信することも、次のように payload という名前のフォームフィールド内に JSON データを送信することもできます (URL エンコードが適用される前)。

1
payload={"text":"Swagger is awesome"}

これは次のように記述できます。

1
openapi: 3.0.4
2
info:
3
  version: 1.0.0
4
  title: Slack Incoming Webhook
5
externalDocs:
6
  url: https://api.slack.com/incoming-webhooks
7

8
servers:
9
  - url: https://hooks.slack.com
10

11
paths:
12
  /services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX:
13
    post:
14
      summary: Post a message to Slack
15
      requestBody:
16
        content:
17
          application/json:
18
            schema:
19
              $ref: "#/components/schemas/Message"
20

21
          application/x-www-form-urlencoded:
22
            schema:
23
              type: object
24
              properties:
25
                payload: # <--- form field that contains the JSON message
26
                  $ref: "#/components/schemas/Message"
27
            encoding:
28
              payload:
29
                contentType: application/json
30

31
      responses:
32
        "200":
33
          description: OK
34

35
components:
36
  schemas:
37
    Message:
38
      title: A Slack message
39
      type: object
40
      properties:
41
        text:
42
          type: string
43
          description: Message text
44
      required:
45
        - text

参照

RequestBody オブジェクト

MediaType オブジェクト

お探しのものが見つかりませんでしたか？コミュニティに質問する
間違いを見つけましたか？お知らせください