コンテンツにスキップ

パラメータの記述

Swagger では、API 操作パラメーターは操作定義の parameters セクションで定義されます。各パラメーターには name、値の type (プリミティブ値パラメーターの場合) または schema (リクエストボディの場合)、およびオプションの description があります。以下に例を示します。

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Gets a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          type: integer
9
          required: true
10
          description: Numeric ID of the user to get.

parameters は配列であるため、YAML では各パラメーター定義の前にダッシュ (-) を付けてリストする必要があります。

パラメーターの種類

Swagger は、パラメーターの場所に基づいて、以下のパラメータータイプを区別します。場所はパラメーターの in キーによって決定されます。例えば、in: query や in: path です。

クエリパラメータ

クエリパラメーターは最も一般的なパラメータータイプです。リクエスト URL の末尾に疑問符 (?) の後に現れ、異なる name=value ペアはアンパサンド (&) で区切られます。クエリパラメーターは必須にもオプションにもなり得ます。

ターミナルウィンドウ
1
GET /pets/findByStatus?status=available
2
GET /notes?offset=100&limit=50

クエリパラメーターを示すには、in: query を使用します。

1
parameters:
2
  - in: query
3
    name: offset
4
    type: integer
5
    description: The number of items to skip before starting to collect the result set.
6
  - in: query
7
    name: limit
8
    type: integer
9
    description: The numbers of items to return.

クエリパラメーターはプリミティブ型のみをサポートします。array を持つことはできますが、items はプリミティブ値型でなければなりません。オブジェクトはサポートされていません。

注: クエリパラメーターとして渡される API キーを記述するには、代わりにセキュリティ定義を使用します。API キーを参照してください。

パスパラメータ

パスパラメータは、変化する可能性のある URL パスの一部です。通常、ID で識別されるユーザーなど、コレクション内の特定の¹リソースを指すために使用されます。URL には複数のパスパラメータを持つことができ、それぞれ中括弧 { } で示されます。

ターミナルウィンドウ
1
GET /users/{id}
2
GET /cars/{carId}/drivers/{driverId}

クライアントがAPIコールを行う際、各パスパラメータは実際の値に置き換えられる必要があります。Swaggerでは、パスパラメータは in: path と必要に応じて他の属性を使用して定義されます。パラメータ名はパスで指定されたものと同じである必要があります。また、パスパラメータは常に必須であるため、required: true を追加することを忘れないでください。以下は GET /users/{id} の例です。

1
paths:
2
  /users/{id}:
3
    get:
4
      parameters:
5
        - in: path
6
          name: id   # Note the name is the same as in the path
7
          required: true
8
          type: integer
9
          minimum: 1
10
          description: The user ID.
11
        responses:
12
          200:
13
            description: OK

パスパラメーターは、GET /users/12,34,56 のように複数値にすることができます。これは、パラメーターの型を array として指定することで実現されます。以下の配列と複数値パラメーターを参照してください。

ヘッダーパラメータ

API 呼び出しでは、HTTP リクエストとともにカスタムヘッダーを送信する必要がある場合があります。Swagger では、カスタムリクエストヘッダーを in: header パラメーターとして定義できます。たとえば、GET /ping への呼び出しで X-Request-ID ヘッダーが必要な場合を考えます。

ターミナルウィンドウ
1
GET /ping HTTP/1.1
2
Host: example.com
3
X-Request-ID: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac

Swagger では、この操作を次のように定義します。

1
paths:
2
  /ping:
3
    get:
4
      summary: Checks if the server is alive.
5
      parameters:
6
        - in: header
7
          name: X-Request-ID
8
          type: string
9
          required: true

同様の方法で、カスタムレスポンスヘッダーを定義できます。

注: Swagger 仕様には、一部のヘッダーに特別なキーワードがあります。

ヘッダー Swagger キーワード 詳細については...
コンテンツタイプ consumes (リクエストコンテンツタイプ)
produces (レスポンスコンテンツタイプ)		 MIME タイプ
承諾 produces MIME タイプ
認証 securityDefinitions, security 認証

フォームパラメーター

フォームパラメーターは、Content-Type が以下のリクエストのペイロードを記述するために使用されます。

  • application/x-www-form-urlencoded (プリミティブ値およびプリミティブ値の配列を POST するために使用されます)。
  • multipart/form-data (ファイルのアップロード、またはファイルとプリミティブデータの組み合わせのために使用されます)。

つまり、操作の consumes プロパティはこれらのコンテンツタイプの一つを指定する必要があります。フォームパラメーターは in: formData として定義されます。これらはプリミティブ (文字列、数値、ブール値) またはプリミティブの配列のみにすることができます (つまり、items の値として $ref を使用することはできません)。また、formData はボディを記述する特定の方法であるため、フォームパラメーターは in: body パラメーターと共存することはできません。フォームパラメーターを説明するために、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: 29
5


6
name=Amy+Smith&fav_number=321

Swagger では、エンドポイントを次のように記述できます。

1
paths:
2
  /survey:
3
    post:
4
      summary: A sample survey.
5
      consumes:
6
        - application/x-www-form-urlencoded
7
      parameters:
8
        - in: formData
9
          name: name
10
          type: string
11
          description: A person's name.
12
        - in: formData
13
          name: fav_number
14
          type: number
15
          description: A person's favorite number.
16
      responses:
17
        200:
18
          description: OK

ファイルアップロード用のフォームパラメーターの定義方法については、ファイルアップロードを参照してください。

必須パラメーターとオプションパラメーター

デフォルトでは、Swagger はすべてのリクエストパラメーターをオプションとして扱います。パラメーターを必須としてマークするには、required: true を追加できます。パスパラメーターは常に必須であるため、required: true を持つ必要があることに注意してください。

1
parameters:
2
  - in: path
3
    name: userId
4
    type: integer
5
    required: true # <----------
6
    description: Numeric ID of the user to get.

デフォルトパラメーター値

オプションのパラメーターのデフォルト値を指定するには、default キーを使用できます。デフォルト値は、クライアントがリクエストでパラメーター値を指定しない場合にサーバーが使用する値です。値の型は、パラメーターのデータ型と同じでなければなりません。典型的な例は、オフセットとリミットのようなページングパラメーターです。

ターミナルウィンドウ
1
GET /users
2
GET /users?offset=30&limit=10

オフセットがデフォルトで 0、リミットがデフォルトで 20 で、範囲が 0 から 100 であると仮定すると、これらのパラメーターは次のように定義されます。

1
parameters:
2
  - in: query
3
    name: offset
4
    type: integer
5
    required: false
6
    default: 0
7
    minimum: 0
8
    description: The number of items to skip before starting to collect the result set.
9
  - in: query
10
    name: limit
11
    type: integer
12
    required: false
13
    default: 20
14
    minimum: 1
15
    maximum: 100
16
    description: The numbers of items to return.

よくある間違い

default キーワードを使用する際には、2つのよくある間違いがあります。

  • default を必須パラメーターまたはプロパティ（例：パスパラメーター）と一緒に使用すること。これは意味がありません。値が必須である場合、クライアントは常にそれを送信する必要があり、デフォルト値は決して使用されません。
  • default をサンプル値を指定するために使用すること。これはデフォルトの意図された用途ではなく、一部の Swagger ツールで予期しない動作につながる可能性があります。この目的のために、仕様の一部の要素は example または examples キーワードをサポートしています。

Enum パラメーター

enum キーワードを使用すると、パラメータ値を固定値のセットに制限できます。enum 値はパラメータの type と同じ型でなければなりません。

1
- in: query
2
  name: status
3
  type: string
4
  enum: [available, pending, sold]

詳細情報: Enum の定義

配列と複数値パラメーター

パス、クエリ、ヘッダー、およびフォームパラメーターは、たとえば次のような値のリストを受け入れることができます。

ターミナルウィンドウ
1
GET /users/12,34,56,78
2
GET /resource?param=value1,value2,value3
3
GET /resource?param=value1&param=value2&param=value3
4


5
POST /resource
6
param=value1&param=value2

複数値パラメーターは、type: array と適切な collectionFormat で定義する必要があります。

1
# color=red,black,white
2
parameters:
3
  - in: query
4
    name: color
5
    type: array
6
    collectionFormat: csv
7
    items:
8
      type: string

collectionFormat は、配列のフォーマット (複数のパラメーターを持つ単一のパラメーター、または同じ名前を持つ複数のパラメーター) および配列項目の区切り文字を指定します。

コレクション形式 説明 例
csv (デフォルト) カンマ区切り値。 foo,bar,baz
ssv スペース区切りの値。 foo bar baz
tsv タブ区切りの値。 "foo\tbar\tbaz"
パイプ パイプ区切りの値。 foo|bar|baz
マルチ 複数値ではなく、複数のパラメーターインスタンス。これは in: query と in: formData のパラメーターのみでサポートされます。 foo=value&foo=another_value

さらに、次のこともできます。

  • minItems と maxItems を使用して配列のサイズを制御する
  • uniqueItems を強制する
  • 配列アイテムを固定された enum 値のセットに制限する。

例えば

1
- in: query
2
  name: color
3
  required: false
4
  type: array
5
  minItems: 1
6
  maxItems: 5
7
  uniqueItems: true
8
  items:
9
    type: string
10
    enum:
11
      [
12
        black,
13
        white,
14
        gray,
15
        red,
16
        pink,
17
        orange,
18
        yellow,
19
        green,
20
        blue,
21
        purple,
22
        brown,
23
      ]

また、このパラメーターが省略された場合にサーバーが使用するデフォルトの配列を指定することもできます。

1
- in: query
2
  name: sort
3
  required: false
4
  type: array
5
  items:
6
    type: string
7
  default: ["-modified", "+id"]

定数パラメーター

単一の可能な値を持つ必須パラメーターとして、定数パラメーターを定義できます。

1
- required: true
2
  enum: [value]

enum プロパティは、可能な値を指定します。この例では、1つの値のみが使用でき、これがユーザーが選択できる Swagger UI で唯一の利用可能な値になります。

注: 定数パラメーターは、デフォルトパラメーター値と同じではありません。定数パラメーターはクライアントによって常に送信されますが、デフォルト値は、パラメーターがクライアントによって送信されない場合にサーバーが使用するものです。

値のないパラメーター

クエリ文字列とフォームデータパラメーターは、名前のみで値を持たない場合があります。

ターミナルウィンドウ
1
GET /foo?metadata
2


3
POST /something
4
foo&bar&baz

そのようなパラメータを記述するには、allowEmptyValue を使用します。

1
- in: query
2
  name: metadata
3
  required: true
4
  type: boolean
5
  allowEmptyValue: true # <-----

共通パラメーター

パスのすべてのメソッドの共通パラメーター

パラメータはパス自体で定義できます。この場合、パラメータはこのパスの下で記述されたすべての操作に存在します。典型的な例は、パスパラメータを介してアクセスされる同じリソースを操作する GET/PUT/PATCH/DELETE 操作です。

1
paths:
2
  /user/{id}:
3
    parameters:
4
      - in: path
5
        name: id
6
        type: integer
7
        required: true
8
        description: The user ID.
9


10
    get:
11
      summary: Gets a user by ID.
12
      ...
13
    patch:
14
      summary: Updates an existing user with the specified ID.
15
      ...
16
    delete:
17
      summary: Deletes the user with the specified ID.
18
      ...

操作レベルで定義された追加のパラメーターは、パスレベルのパラメーターと組み合わせて使用されます。

1
paths:
2
  /users/{id}:
3
    parameters:
4
      - in: path
5
        name: id
6
        type: integer
7
        required: true
8
        description: The user ID.
9


10
    # GET/users/{id}?metadata=true
11
    get:
12
      summary: Gets a user by ID.
13
      # Note we only define the query parameter, because the {id} is defined at the path level.
14
      parameters:
15
        - in: query
16
          name: metadata
17
          type: boolean
18
          required: false
19
          description: If true, the endpoint returns only the user metadata.
20
      responses:
21
        200:
22
          description: OK

特定のパスレベルパラメータは操作レベルで上書きできますが、削除することはできません。

1
paths:
2
  /users/{id}:
3
    parameters:
4
      - in: path
5
        name: id
6
        type: integer
7
        required: true
8
        description: The user ID.
9


10
    # DELETE /users/{id} - uses a single ID.
11
    # Reuses the {id} parameter definition from the path level.
12
    delete:
13
      summary: Deletes the user with the specified ID.
14
      responses:
15
        204:
16
          description: User was deleted.
17


18
    # GET /users/id1,id2,id3 - uses one or more user IDs.
19
    # Overrides the path-level {id} parameter.
20
    get:
21
      summary: Gets one or more users by ID.
22
      parameters:
23
        - in: path
24
          name: id
25
          required: true
26
          description: A comma-separated list of user IDs.
27
          type: array
28
          items:
29
            type: integer
30
          collectionFormat: csv
31
          minItems: 1
32
      responses:
33
        200:
34
          description: OK

異なるパスにおける共通パラメーター

異なるAPIパスには、ページネーションパラメータなどの共通パラメータがある場合があります。共通パラメータはグローバルな parameters セクションで定義し、$ref を介して個々の操作で参照できます。

1
parameters:
2
  offsetParam: # <-- Arbitrary name for the definition that will be used to refer to it.
3
    # Not necessarily the same as the parameter name.
4
    in: query
5
    name: offset
6
    required: false
7
    type: integer
8
    minimum: 0
9
    description: The number of items to skip before starting to collect the result set.
10
  limitParam:
11
    in: query
12
    name: limit
13
    required: false
14
    type: integer
15
    minimum: 1
16
    maximum: 50
17
    default: 20
18
    description: The numbers of items to return.
19
paths:
20
  /users:
21
    get:
22
      summary: Gets a list of users.
23
      parameters:
24
        - $ref: "#/parameters/offsetParam"
25
        - $ref: "#/parameters/limitParam"
26
      responses:
27
        200:
28
          description: OK
29
  /teams:
30
    get:
31
      summary: Gets a list of teams.
32
      parameters:
33
        - $ref: "#/parameters/offsetParam"
34
        - $ref: "#/parameters/limitParam"
35
      responses:
36
        200:
37
          description: OK

グローバルな parameters はすべての操作に適用されるパラメーターではなく、単に再利用しやすいグローバルな定義であることに注意してください。

パラメーターの依存関係

Swagger はパラメータの依存関係や相互排他的なパラメータをサポートしていません。https://github.com/OAI/OpenAPI-Specification/issues/256 で未解決の機能リクエストがあります。できることとしては、パラメータの説明に制約を文書化し、400 Bad Request レスポンスでロジックを定義することです。例えば、相対的な日付範囲 (rdate) または正確な範囲 (start_date + end_date) のいずれかを受け入れる /report エンドポイントを考えてみましょう。

ターミナルウィンドウ
1
GET /report?rdate=Today
2
GET /report?start_date=2016-11-15&end_date=2016-11-20

このエンドポイントは次のように記述できます。

1
paths:
2
  /report:
3
    get:
4
      parameters:
5
        - name: rdate
6
          in: query
7
          type: string
8
          description: >
9
            A relative date range for the report, such as `Today` or `LastWeek`.
10
            For an exact range, use `start_date` and `end_date` instead.
11
        - name: start_date
12
          in: query
13
          type: string
14
          format: date
15
          description: >
16
            The start date for the report. Must be used together with `end_date`.
17
            This parameter is incompatible with `rdate`.
18
        - name: end_date
19
          in: query
20
          type: string
21
          format: date
22
          description: >
23
            The end date for the report. Must be used together with `start_date`.
24
            This parameter is incompatible with `rdate`.
25
      responses:
26
        400:
27
          description: Either `rdate` or `start_date`+`end_date` are required.

FAQ

「type」と「schema」はいつ使い分けるべきですか？

schema は in: body パラメーターでのみ使用されます。その他のパラメーターは、type: string のようなプリミティブ型、またはプリミティブの array を期待します。

オブジェクトをクエリパラメーターとして使用できますか？

OpenAPI 3.0 では可能ですが、2.0 ではできません。

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