docs: https://swagger.io/docs/specification/describing-parameters/
## 概要
OpenAPI 3.0 では、パラメータは operation または path の `parameters` セクション内に定義される。
パラメータを定義するにはその名前 (`name`) とロケーション (`in`)、データ型 (`schmea` 内などで定義) を指定する。
```yaml
paths:
/users/{userId}:
get:
summary: Get a user by ID
parameters:
- in: path
name: userId
schema:
type: integer
required: true
description: Numeric ID of the user to get
```
`parameters` は配列 (array) であるため、YAML ファイルではダッシュを使ってリストされる必要がある。
## パラメータタイプ
OpenAPI 3.0 では以下のパラメータタイプをパラメータの場所によって識別する。パラメータのロケーションは `in` キーで例えば `in: query` のように決定される。
パラメータ | 例
--|--
path parameter | `/users/{id}`
query parameters | `/users?role=admin`
header parameters | `X-MyHeader: value`
cookie parameters | `Cookie` ヘッダー内に `Cookie:debug=0;csrftoken=BUSe35dohU3O1MZvDCU` のように渡される
## パスパラメータ
パスパラメータは URL パスの変数の部分で、ID によるユーザー認証やコレクション内の特定のリソースを指定するなどの使われ方をする。
URL は複数のパスパラメータを持つことが出来き、各パラメータは `{}` で表記される。
```sh
GET /users/{id}
GET /cars/{carId}/drivers/{driverId}
GET /report.{format}
```
各パスパラメータはクライアントが API コールを行う際に実際の呼び出しの値で置き換えられる必要がある。
OpenAPI では、パスパラメータは `in:path` で定義される。パラメータ名はパスに指定したものとを同じである必要がある。また、パスパラメータは常に必須となるので `required:true` を追加することにも注意する。
```yaml
# /user/{id} エンドポイントの書き方
paths:
/users/{id}:
get:
parameters:
- in: path
name: id
required: true
schema:
type: integer
minimum: 1
description: The user ID
```
パスパラメータに array や object が含まれる場合のシリアライズ方法はいくつか種類があることに注意。
- Path-style expansion(matrix)
- セミコロンがプレフィクス
- `/map/point;x=50,y=20`
- Lavel expansion
- ドットがプレフィクス
- `/color.R=100.G=200.B=150`
- Simple-style
- カンマがプレフィクス
- `/users/12,34,56`
## クエリパラメータ
クエリパラメータはパラメータの中で最もよく使われるタイプであり、リクエスト URL の再度に `?` マークの後に現れる。複数個ある場合には `&` で区切られた `name=value` のペアとなる。クエリパラメータは必須 (required) か省略可能 (optional) となる。
```sh
GET /pets/findByStatus?status=available
GET /notes?offset=100&limit=50
```
`in: query` を使うことでクエリパラメータを定義できる。
```yaml
parameters:
- in: query
name: offset
schema:
type: integer
description: The number of items to skip before starting to collect the result set
- in: query
name: limit
schema:
type: integer
description: The numbers of items to return
```
クエリパラメータには==プリミティブ型の値と配列、オブジェクトを指定でき==、OpenAPI 3.0 ではオブジェクトと配列をクエリストリングにシリアライズするいくつかの方法を提供する。