OAS 2 このページは、OpenAPI仕様バージョン2（旧称Swagger）に適用されます。最新バージョンについては、OpenAPI 3ページをご覧ください。

パラメータの説明

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

paths:
  /users/{userId}:
    get:
      summary: Gets a user by ID.
      parameters:
        - in: path
          name: userId
          type: integer
          required: true
          description: Numeric ID of the user to get.

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

パラメータの種類

Swaggerは、パラメータの位置に基づいて、次のパラメータの種類を区別します。位置は、パラメータのinキー（例：in: queryまたはin: path）によって決定されます。

• クエリパラメータ（例：/users?role=admin）
• パスパラメータ（例：/users/{id}）
• ヘッダーパラメータ（例：X-MyHeader: Value）
• POST、PUT、およびPATCHリクエストのボディを記述するボディパラメータ（リクエストボディの説明を参照）
• フォームパラメータ – Content-Typeがapplication/x-www-form-urlencodedおよびmultipart/form-dataのリクエストのペイロードを記述するために使用されるさまざまなボディパラメータ（後者は通常、ファイルのアップロードに使用されます）

クエリパラメータ

クエリパラメータは、最も一般的なパラメータの種類です。クエリパラメータは、疑問符（?）の後にリクエストURLの最後に表示され、異なるname=valueペアはアンパサンド（&）で区切られます。クエリパラメータは必須とオプションの両方があります。

GET /pets/findByStatus?status=available
GET /notes?offset=100&limit=50

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

     parameters:
        - in: query
          name: offset
          type: integer
          description: The number of items to skip before starting to collect the result set.
        - in: query
          name: limit
          type: integer
          description: The numbers of items to return.

クエリパラメータはプリミティブ型のみをサポートします。配列を使用できますが、itemsはプリミティブ値型である必要があります。オブジェクトはサポートされていません。

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

パスパラメータ

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

GET /users/{id}
GET /cars/{carId}/drivers/{driverId}

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

paths:
  /users/{id}:
    get:
      parameters:
        - in: path
          name: id   # Note the name is the same as in the path
          required: true
          type: integer
          minimum: 1
          description: The user ID.
       responses:
         200:
           description: OK

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

ヘッダーパラメータ

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

GET /ping HTTP/1.1
Host: example.com
X-Request-ID: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac

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

paths:
  /ping:
    get:
      summary: Checks if the server is alive.
      parameters:
        - in: header
          name: X-Request-ID
          type: string
          required: true

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

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

ヘッダー	Swaggerキーワード	詳細については…を参照してください。
Content-Type	consumes（リクエストコンテンツタイプ） produces（レスポンスコンテンツタイプ）	MIMEタイプ
Accept	produces	MIMEタイプ
認証	securityDefinitions、security	認証

フォームパラメータ

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

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

つまり、操作のconsumesプロパティは、これらのコンテンツタイプのいずれかを指定する必要があります。フォームパラメータはin: formDataとして定義されます。プリミティブ（文字列、数値、ブール値）またはプリミティブの配列のみを指定できます（つまり、$refをitems値として使用することはできません）。また、formDataはボディを記述する特定の方法であるため、フォームパラメータはin: bodyパラメータと共存できません。フォームパラメータを説明するために、HTML POSTフォームを考えてみましょう。

<form action="http://example.com/survey" method="post">
  <input type="text"   name="name" />
  <input type="number" name="fav_number" />
  <input type="submit"/>
 </form>

このフォームは、フォームのエンドポイントにデータをPOSTします。

POST /survey HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 29

name=Amy+Smith&fav_number=321

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

paths:
  /survey:
    post:
      summary: A sample survey.
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: name
          type: string
          description: A person's name.
        - in: formData
          name: fav_number
          type: number
          description: A person's favorite number.
      responses:
        200:
          description: OK

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

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

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

      parameters:
        - in: path
          name: userId
          type: integer
          required: true    # <----------
          description: Numeric ID of the user to get.

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

オプションのパラメータのデフォルト値を指定するには、defaultキーを使用できます。デフォルト値は、クライアントがリクエストでパラメータ値を供給しない場合にサーバーが使用する値です。値の型は、パラメータのデータ型と同じである必要があります。一般的な例としては、オフセットや制限などのページングパラメータがあります。

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

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

      parameters:
        - in: query
          name: offset
          type: integer
          required: false
          default: 0
          minimum: 0
          description: The number of items to skip before starting to collect the result set.
        - in: query
          name: limit
          type: integer
          required: false
          default: 20
          minimum: 1
          maximum: 100
          description: The numbers of items to return.

よくある間違い

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

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

列挙パラメータ

enumキーワードを使用すると、パラメータ値を固定された値のセットに制限できます。列挙値は、パラメータtypeと同じ型である必要があります。

        - in: query
          name: status
          type: string
          enum: [available, pending, sold]

詳細情報：列挙の定義.

配列と複数値パラメータ

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

GET /users/12,34,56,78
GET /resource?param=value1,value2,value3
GET /resource?param=value1&param=value2&param=value3

POST /resource
param=value1&param=value2

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

      # color=red,black,white
      parameters:
        - in: query
          name: color
          type: array
          collectionFormat: csv
          items:
            type: string

collectionFormatは、配列形式（複数の値を持つ単一のパラメータ、または同じ名前の複数のパラメータ）と配列項目のセパレータを指定します。

collectionFormat	説明	例
csv（デフォルト）	カンマ区切り値。	foo,bar,baz
ssv	スペース区切り値。	foo bar baz
tsv	タブ区切り値。	"foo bar baz"
pipes	パイプ区切り値。	foo|bar|baz
multi	複数の値ではなく、複数のパラメータインスタンス。これは、in: queryおよびin: formDataパラメータでのみサポートされています。	foo=value&foo=another_value

さらに、

• minItemsとmaxItemsを使用して配列のサイズを制御したり、
• uniqueItemsを適用したり、
• 配列の項目を固定されたenum値のセットに制限したりできます。

例

        - in: query
          name: color
          required: false
          type: array
          minItems: 1
          maxItems: 5
          uniqueItems: true
          items:
            type: string
            enum: [black, white, gray, red, pink, orange, yellow, green, blue, purple, brown]

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

        - in: query
          name: sort
          required: false
          type: array
          items:
            type: string
          default: ["-modified", "+id"]

定数パラメータ

定数パラメータは、可能な値が1つしかない必須パラメータとして定義できます。

- required: true
  enum: [value]

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

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

値を持たないパラメータ

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

GET /foo?metadata

POST /something
foo&bar&baz

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

        - in: query
          name: metadata
          required: true
          type: boolean
          allowEmptyValue: true  # <-----

共通パラメータ

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

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

paths:
  /user/{id}:
    parameters:
      - in: path
        name: id
        type: integer
        required: true
        description: The user ID.

    get:
      summary: Gets a user by ID.
      ...
    patch:
      summary: Updates an existing user with the specified ID.
      ...
    delete:
      summary: Deletes the user with the specified ID.
      ...

操作レベルで定義された追加のパラメータは、パスレベルのパラメータと共に使用されます。

paths:
  /users/{id}:
    parameters:
      - in: path
        name: id
        type: integer
        required: true
        description: The user ID.

    # GET/users/{id}?metadata=true
    get:
      summary: Gets a user by ID.
      # Note we only define the query parameter, because the {id} is defined at the path level.
      parameters:
        - in: query
          name: metadata
          type: boolean
          required: false
          description: If true, the endpoint returns only the user metadata.
      responses:
        200:
          description: OK

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

paths:
  /users/{id}:
    parameters:
      - in: path
        name: id
        type: integer
        required: true
        description: The user ID.

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

    # GET /users/id1,id2,id3 - uses one or more user IDs.
    # Overrides the path-level {id} parameter.
    get:
      summary: Gets one or more users by ID.
      parameters:
        - in: path
          name: id
          required: true
          description: A comma-separated list of user IDs.
          type: array
          items:
            type: integer
          collectionFormat: csv
          minItems: 1
      responses:
        200:
          description: OK

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

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

parameters:
  offsetParam:  # <-- Arbitrary name for the definition that will be used to refer to it.
                # Not necessarily the same as the parameter name.
    in: query
    name: offset
    required: false
    type: integer
    minimum: 0
    description: The number of items to skip before starting to collect the result set.
  limitParam:
    in: query
    name: limit
    required: false
    type: integer
    minimum: 1
    maximum: 50
    default: 20
    description: The numbers of items to return.
paths:
  /users:
    get:
      summary: Gets a list of users.
      parameters:
        - $ref: '#/parameters/offsetParam'
        - $ref: '#/parameters/limitParam'
      responses:
        200:
          description: OK
  /teams:
    get:
      summary: Gets a list of teams.
      parameters:
        - $ref: '#/parameters/offsetParam'
        - $ref: '#/parameters/limitParam'
      responses:
        200:
          description: OK

グローバルparametersは、すべての操作に適用されるパラメータではありません。簡単に再利用できるグローバル定義です。

パラメータの依存関係

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

GET /report?rdate=Today
GET /report?start_date=2016-11-15&end_date=2016-11-20

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

paths:
  /report:
    get:
      parameters:
        - name: rdate
          in: query
          type: string
          description: >
             A relative date range for the report, such as `Today` or `LastWeek`.
             For an exact range, use `start_date` and `end_date` instead.
        - name: start_date
          in: query
          type: string
          format: date
          description: >
            The start date for the report. Must be used together with `end_date`.
            This parameter is incompatible with `rdate`.
        - name: end_date
          in: query
          type: string
          format: date
          description: >
            The end date for the report. Must be used together with `start_date`.
            This parameter is incompatible with `rdate`.
      responses:
        400:
          description: Either `rdate` or `start_date`+`end_date` are required.

FAQ

"type"と"schema"をいつ使用するべきですか？

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

クエリパラメータとしてオブジェクトを持つことはできますか？

これはOpenAPI 3.0では可能ですが、2.0では不可能です。

  

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