OAS 2 このページは、OpenAPI Specification ver. 2 (旧Swagger)に適用されます。最新バージョンについては、OpenAPI 3ページをご覧ください。

リクエストボディの記述

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

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

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

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

オブジェクトペイロード（JSONなど）

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

{
  "userName":  "Trillian",
  "firstName": "Tricia",
  "lastName":  "McMillan"
}

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

paths:
  /users:
    post:
      summary: Creates a new user.
      consumes:
        - application/json
      parameters:
        - in: body
          name: user
          description: The user to create.
          schema:
            type: object
            required:
              - userName
            properties:
              userName:
                type: string
              firstName:
                type: string
              lastName:
                type: string
      responses:
        201:
          description: Created

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

paths:
  /users:
    post:
      summary: Creates a new user.
      consumes:
        - application/json
      parameters:
        - in: body
          name: user
          description: The user to create.
          schema:
            $ref: '#/definitions/User'     # <----------
      responses:
        200:
          description: OK
definitions:
  User:           # <----------
    type: object
    required:
      - userName
    properties:
      userName:
        type: string
      firstName:
        type: string
      lastName:
        type: string

プリミティブボディ

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

POST /status HTTP/1.1
Host: api.example.com
Content-Type: text/plain
Content-Length: 42

Time is an illusion. Lunchtime doubly so.

Swagger定義

paths:
  /status:
    post:
      summary: Updates the status message.
      consumes:
        - text/plain      # <----------
      parameters:
        - in: body
          name: status
          required: true
          schema:
            type: string  # <----------
      responses:
        200:
          description: Success!

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