リクエストボディの記述

POST、PUT、PATCH リクエストには、JSON や XML データなどのリクエストボディ（ペイロード）を含めることができます。Swagger の用語では、リクエストボディはボディパラメーターと呼ばれます。ボディパラメーターは 1 つしか指定できませんが、操作には他のパラメーター（パス、クエリ、ヘッダー）が含まれる場合があります。

注: application/x-www-form-urlencoded および multipart/form-data リクエストのペイロードは、ボディパラメーターではなく、フォームパラメーターを使用して記述されます。

ボディパラメーターは、操作のパラメーターセクションで定義され、以下を含みます。

in: body
ボディのデータ型と構造を記述する schema。データ型は通常オブジェクトですが、プリミティブ（文字列や数値など）や配列も可能です。
オプションの description。
ペイロード名。必須ですが無視されます（ドキュメント目的でのみ使用されます）。

オブジェクトペイロード (JSONなど)

多くの API は、JSON などのオブジェクトとしてデータを送信します。schema はオブジェクトの場合、type: object とそのオブジェクトのプロパティを指定する必要があります。たとえば、この JSON ボディを持つ POST /users 操作は次のようになります。

1
{
2
  "userName": "Trillian",
3
  "firstName": "Tricia",
4
  "lastName": "McMillan"
5
}

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

1
paths:
2
  /users:
3
    post:
4
      summary: Creates a new user.
5
      consumes:
6
        - application/json
7
      parameters:
8
        - in: body
9
          name: user
10
          description: The user to create.
11
          schema:
12
            type: object
13
            required:
14
              - userName
15
            properties:
16
              userName:
17
                type: string
18
              firstName:
19
                type: string
20
              lastName:
21
                type: string
22
      responses:
23
        201:
24
          description: Created

注: ボディパラメーターの名前は無視されます。ドキュメント目的でのみ使用されます。よりモジュール化されたスタイルにするには、スキーマ定義をグローバルな definitions セクションに移動し、$ref を使用してそれらを参照できます。

1
paths:
2
  /users:
3
    post:
4
      summary: Creates a new user.
5
      consumes:
6
        - application/json
7
      parameters:
8
        - in: body
9
          name: user
10
          description: The user to create.
11
          schema:
12
            $ref: "#/definitions/User" # <----------
13
      responses:
14
        200:
15
          description: OK
16
definitions:
17
  User: # <----------
18
    type: object
19
    required:
20
      - userName
21
    properties:
22
      userName:
23
        type: string
24
      firstName:
25
        type: string
26
      lastName:
27
        type: string

プリミティブボディ

単一の値だけを POST/PUT したいですか？問題ありません。ボディスキーマの型を、文字列や数値などのプリミティブとして定義できます。生の要求

1
POST /status HTTP/1.1
2
Host: api.example.com
3
Content-Type: text/plain
4
Content-Length: 42
5

6
Time is an illusion. Lunchtime doubly so.

Swagger の定義

1
paths:
2
  /status:
3
    post:
4
      summary: Updates the status message.
5
      consumes:
6
        - text/plain # <----------
7
      parameters:
8
        - in: body
9
          name: status
10
          required: true
11
          schema:
12
            type: string # <----------
13
      responses:
14
        200:
15
          description: Success!

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