コンテンツにスキップ

パラメータの記述

OpenAPI 3.0では、パラメータは操作またはパスのparametersセクションで定義されます。パラメータを記述するには、そのname、場所（in）、データ型（schemaまたはcontentのいずれかで定義）、およびdescriptionやrequiredなどの他の属性を指定します。以下に例を示します。

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

parametersは配列であるため、YAMLでは各パラメータ定義の前にダッシュ（-）を付けてリストする必要があることに注意してください。

パラメータタイプ

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

パスパラメータ

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

1
GET /users/{id}
2
GET /cars/{carId}/drivers/{driverId}
3
GET /report.{format}

クライアントがAPIコールを行う際、各パスパラメータは実際の値に置き換えられる必要があります。OpenAPIでは、パスパラメータはin: pathを使用して定義されます。パラメータ名は、パスで指定されたものと同じである必要があります。また、パスパラメータは常に必須であるため、required: trueを追加することを忘れないでください。例えば、/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
          schema:
9
            type: integer
10
            minimum: 1
11
          description: The user ID

配列とオブジェクトを含むパスパラメータは、さまざまな方法でシリアル化できます

  • パススタイル展開 (matrix) – セミコロン区切り、例: /map/point;x=50;y=20
  • ラベル展開 – ドット区切り、例: /color.R=100.G=200.B=150
  • シンプルスタイル – カンマ区切り、例: /users/12,34,56

シリアル化方法は、styleおよびexplodeキーワードで指定されます。詳細については、パラメータのシリアル化を参照してください。

クエリパラメータ

クエリパラメータは、最も一般的なタイプのパラメータです。これらは、リクエスト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
    schema:
5
      type: integer
6
    description: The number of items to skip before starting to collect the result set
7
  - in: query
8
    name: limit
9
    schema:
10
      type: integer
11
    description: The numbers of items to return

注：クエリパラメータとして渡されるAPIキーを記述するには、代わりにsecuritySchemesとsecurityを使用してください。APIキーを参照してください。

クエリパラメータは、プリミティブ値、配列、およびオブジェクトにすることができます。OpenAPI 3.0は、クエリ文字列内のオブジェクトと配列をシリアル化するためのいくつかの方法を提供します。

配列は次のようにシリアル化できます。

  • form – explodeキーワードによって、/products?color=blue,green,red または /products?color=blue&color=green
  • spaceDelimited (OpenAPI 2.0のcollectionFormat: ssvと同じ) – /products?color=blue%20green%20red
  • pipeDelimited (OpenAPI 2.0のcollectionFormat: pipesと同じ) – /products?color=blue|green|red

オブジェクトは以下のようにシリアル化できます。

  • form – explodeキーワードによって、/points?color=R,100,G,200,B,150または/points?R=100&G=200&B=150
  • deepObject – /points?color[R]=100&color[G]=200&color[B]=150

シリアル化方法は、styleおよびexplodeキーワードで指定されます。詳細については、パラメータのシリアル化を参照してください。

クエリパラメータ内の予約文字

RFC 3986は、URIコンポーネントの区切り文字として使用される予約文字:/?#[]@!$&'()*+,;=のセットを定義しています。これらの文字をクエリパラメータ値で文字通り使用する必要がある場合、通常はパーセントエンコードされます。たとえば、/は%2F（または%2f）としてエンコードされるため、パラメータ値quotes/h2g2.txtは次のように送信されます。

1
GET /file?path=quotes%2Fh2g2.txt

パーセントエンコードされないクエリパラメータが必要な場合は、パラメータ定義にallowReserved: trueを追加します。

1
parameters:
2
  - in: query
3
    name: path
4
    required: true
5
    schema:
6
      type: string
7
    allowReserved: true # <-----

この場合、パラメータ値は次のように送信されます。

1
GET /file?path=quotes/h2g2.txt

ヘッダーパラメータ

APIコールでは、HTTPリクエストとともにカスタムヘッダーを送信する必要がある場合があります。OpenAPIを使用すると、カスタムリクエストヘッダーを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

OpenAPI 3.0 を使用して、この操作を次のように定義します。

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
          schema:
9
            type: string
10
            format: uuid
11
          required: true

同様に、カスタムレスポンスヘッダーを定義できます。ヘッダーパラメータはプリミティブ、配列、オブジェクトにすることができます。配列とオブジェクトはsimpleスタイルを使用してシリアル化されます。詳細については、パラメータシリアル化を参照してください。

注：Accept、Content-Type、Authorizationという名前のヘッダーパラメータは許可されません。これらのヘッダーを記述するには、対応するOpenAPIキーワードを使用してください。

ヘッダー OpenAPIキーワード 詳細については…
Content-Type リクエストコンテンツタイプ: requestBody.content.<media-type>

レスポンスコンテンツタイプ: responses.<code>.content.<media-type>		 リクエストボディの記述,
レスポンスの記述,
メディアタイプ
Accept responses.<code>.content.<media-type> レスポンスの記述,
メディアタイプ
認証 securitySchemes, security 認証

操作は、Cookie: name=valueのようにCookieヘッダーでもパラメータを渡すことができます。複数のクッキーパラメータは、同じヘッダーでセミコロンとスペースで区切られて送信されます。

1
GET /api/users
2
Host: example.com
3
Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCUOJ

クッキーパラメータを定義するにはin: cookieを使用します

1
parameters:
2
  - in: cookie
3
    name: debug
4
    schema:
5
      type: integer
6
      enum: [0, 1]
7
      default: 0
8
  - in: cookie
9
    name: csrftoken
10
    schema:
11
      type: string

クッキーパラメータはプリミティブ値、配列、オブジェクトにすることができます。配列とオブジェクトはformスタイルを使用してシリアル化されます。詳細については、パラメータのシリアル化を参照してください。

注：クッキー認証を定義するには、代わりにAPIキーを使用してください。

必須およびオプションのパラメータ

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

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

スキーマ vs. コンテンツ

パラメータの内容を記述するには、schemaまたはcontentキーワードを使用できます。これらは相互に排他的であり、異なるシナリオで使用されます。ほとんどの場合、schemaを使用します。これは、プリミティブ値、および文字列にシリアル化された単純な配列とオブジェクトを記述できます。配列およびオブジェクトパラメータのシリアル化方法は、そのパラメータで使用されるstyleおよびexplodeキーワードによって定義されます。

1
parameters:
2
  - in: query
3
    name: color
4
    schema:
5
      type: array
6
      items:
7
        type: string
8


9
    # Serialize as color=blue,black,brown (default)
10
    style: form
11
    explode: false

contentは、styleやexplodeでカバーされない複雑なシリアル化シナリオで使用されます。たとえば、次のようにクエリ文字列にJSON文字列を送信する必要がある場合です。

1
filter={"type":"t-shirt","color":"blue"}

この場合、以下に示すように、パラメータschemaをcontent/<media-type>でラップする必要があります。schemaはパラメータのデータ構造を定義し、メディアタイプ（この例ではapplication/json）はシリアル化形式を記述する外部仕様への参照として機能します。

1
parameters:
2
  - in: query
3
    name: filter
4


5
    # Wrap 'schema' into 'content.<media-type>'
6
    content:
7
      application/json: # <---- media type indicates how to serialize / deserialize the parameter content
8
        schema:
9
          type: object
10
          properties:
11
            type:
12
              type: string
13
            color:
14
              type: string

Swagger UI および Swagger Editor のユーザーへ: content を持つパラメータは、Swagger UI 3.23.7 以降および Swagger Editor 3.6.34 以降でサポートされています。

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

オプションのパラメータのデフォルト値を指定するには、パラメータスキーマでdefaultキーワードを使用します。デフォルト値とは、クライアントがリクエストでパラメータ値を指定しなかった場合にサーバーが使用する値です。値の型は、パラメータのデータ型と同じでなければなりません。典型的な例は、offsetやlimitなどのページングパラメータです。

1
GET /users
2
GET /users?offset=30&limit=10

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

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

よくある間違い

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

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

Enumパラメータ

パラメータのschemaにenumを追加することで、パラメータを固定された値のセットに制限することができます。enum値は、パラメータのデータ型と同じタイプでなければなりません。

1
parameters:
2
  - in: query
3
    name: status
4
    schema:
5
      type: string
6
      enum:
7
        - available
8
        - pending
9
        - sold

詳細情報: 列挙型の定義。

定数パラメータ

1つの値のみを持つ必須パラメータとして定数パラメータを定義することができます

1
parameters:
2
  - in: query
3
    name: rel_date
4
    required: true
5
    schema:
6
      type: string
7
      enum:
8
        - now

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

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

空値およびヌル許容パラメータ

クエリ文字列パラメータは、次のように名前だけで値がない場合があります。

1
GET /foo?metadata

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

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

OpenAPI 3.0では、スキーマでnullableもサポートされており、操作パラメータがnull値を持つことができます。たとえば、次のスキーマはC#のint?とJavaのjava.lang.Integerに対応します。

1
schema:
2
  type: integer
3
  format: int32
4
  nullable: true

注：nullableはオプションのパラメータや空値のパラメータとは異なります。nullableはパラメータ値がnullになりうることを意味します。特定の実装では、存在しないパラメータや空値のパラメータをnullにマッピングすることを選択するかもしれませんが、厳密に言えばこれらは同じものではありません。

パラメータ例

パラメータにexampleまたは複数のexamplesを指定できます。例の値はパラメータスキーマと一致する必要があります。単一の例:

1
parameters:
2
  - in: query
3
    name: limit
4
    schema:
5
      type: integer
6
      minimum: 1
7
    example: 20

複数の名前付き例

1
parameters:
2
  - in: query
3
    name: ids
4
    description: One or more IDs
5
    required: true
6
    schema:
7
      type: array
8
      items:
9
        type: integer
10
    style: form
11
    explode: false
12
    examples:
13
      oneId:
14
        summary: Example of a single ID
15
        value: [5] # ?ids=5
16
      multipleIds:
17
        summary: Example of multiple IDs
18
        value: [1, 5, 7] # ?ids=1,5,7

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

非推奨パラメータ

deprecated: true を使用して、パラメータを非推奨としてマークします。

1
- in: query
2
  name: format
3
  required: true
4
  schema:
5
    type: string
6
    enum: [json, xml, yaml]
7
  deprecated: true
8
  description: Deprecated, use the appropriate `Accept` header instead.

共通パラメータ

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

パスのすべての操作で共有されるパラメータは、操作レベルではなくパスレベルで定義できます。パスレベルのパラメータは、そのパスのすべての操作に継承されます。典型的なユースケースは、パスパラメータを介してアクセスされるリソースを操作するGET/PUT/PATCH/DELETE操作です。

1
paths:
2
  /user/{id}:
3
    parameters:
4
      - in: path
5
        name: id
6
        schema:
7
          type: integer
8
        required: true
9
        description: The user ID
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
        schema:
7
          type: integer
8
        required: true
9
        description: The user ID.
10


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

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

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


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


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

様々なパスの共通パラメータ

異なるAPIパスには、ページネーションパラメータなどの共通パラメータが含まれる場合があります。共通パラメータはグローバルcomponentsセクションのparameters以下に定義し、$refを介して他の場所から参照できます。

1
components:
2
  parameters:
3
    offsetParam: # <-- Arbitrary name for the definition that will be used to refer to it.
4
      # Not necessarily the same as the parameter name.
5
      in: query
6
      name: offset
7
      required: false
8
      schema:
9
        type: integer
10
        minimum: 0
11
      description: The number of items to skip before starting to collect the result set.
12
    limitParam:
13
      in: query
14
      name: limit
15
      required: false
16
      schema:
17
        type: integer
18
        minimum: 1
19
        maximum: 50
20
        default: 20
21
      description: The numbers of items to return.
22


23
paths:
24
  /users:
25
    get:
26
      summary: Gets a list of users.
27
      parameters:
28
        - $ref: "#/components/parameters/offsetParam"
29
        - $ref: "#/components/parameters/limitParam"
30
      responses:
31
        "200":
32
          description: OK
33
  /teams:
34
    get:
35
      summary: Gets a list of teams.
36
      parameters:
37
        - $ref: "#/components/parameters/offsetParam"
38
        - $ref: "#/components/parameters/limitParam"
39
      responses:
40
        "200":
41
          description: OK

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

パラメータ依存関係

OpenAPI 3.0 はパラメータの依存関係や排他的パラメータをサポートしていません。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
          schema:
8
            type: string
9
          description: >
10
            A relative date range for the report, such as `Today` or `LastWeek`.
11
            For an exact range, use `start_date` and `end_date` instead.
12
        - name: start_date
13
          in: query
14
          schema:
15
            type: string
16
            format: date
17
          description: >
18
            The start date for the report. Must be used together with `end_date`.
19
            This parameter is incompatible with `rdate`.
20
        - name: end_date
21
          in: query
22
          schema:
23
            type: string
24
            format: date
25
          description: >
26
            The end date for the report. Must be used together with `start_date`.
27
            This parameter is incompatible with `rdate`.
28
      responses:
29
        "400":
30
          description: Either `rdate` or `start_date`+`end_date` are required.

参照

パラメーターオブジェクト

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