OpenAPI 入門 Part2 | リクエストの定義 Parameter, Body

前回は、レスポンス周りの基本的な書き方を紹介したので、今回はリクエスト周りの基本を紹介します.

Parameter Object

Parameter Objectはリソースを特定するために指定するフィールドの総称です.

以下の2つのフィールドは、必ず指定する必要があります.

• name: path parameterとして定義した変数名
• in: パラメーターを定義した場所. クエリーなのかパスなのか

path parameterの定義方法

実際に、path parameterの定義方法を確認していきます.

openapi.yaml

...
paths:
  /users/{id}:
    get:
      parameters:
      - name: id
        in: path
        schema:
          type: string
        required: true

path parameter を指定する場合は、{変数名}で定義します.
name: 定義した変数名
in: パスパラメータなのでpath
schema type: idの型を指定
required: path parameter の場合、trueで定義してあげる必要があります

query parameter の定義方法

/users?id=hogehogeのようにクエリを使いたい時は簡単です.
path parameter の時は、in: pathにしていたものを in: queryに変えるだけです.

openapi.yaml

...
paths:
  /users:
    get:
      parameters:
      - name: id
        in: query
        schema:
          type: string

requiredを指定しなくてもいいです. またクエリなので、エンドポイントは/usersのみになります.

Request Body Object

Parameter Objectと同じくリソースを特定するためのフィールドの集まりです.
今回の場合は、bodyに指定する値を定義しているオブジェクトです.

request bodyの定義方法

ユーザーの情報を更新するPUTを例に解説します.

openapi.yaml

...
paths:
  /users:
    put:
      requestBody: 
        content:
          application/json:
            schema:
              type: object
              properties:
                age: 
                  type: integer
                name:
                  type: string            

contentのタイプをJSONの場合は、application/jsonで指定
Bodyの中身はschema以降に書きます.

まとめ

今回は、OpenAPIを使ってパスパラメータ,クエリパラメータ,bodyを定義する方法を学びました.

次回は、この定義を綺麗に書く方法を紹介するリファクタリング回です. お楽しみに！