パラメータのシリアル化
シリアル化とは、データ構造やオブジェクトの状態を、後で送信および再構築できる形式に変換することです。OpenAPI 3.0は、操作パラメーター (パス、クエリ、ヘッダー、クッキー) の配列とオブジェクトをサポートしており、これらのパラメーターをどのようにシリアル化するかを指定できます。シリアル化方法は、style と explode のキーワードによって定義されます。
styleは、複数の値がどのように区切られるかを定義します。使用可能なスタイルは、パラメーターの場所 (パス、クエリ、ヘッダー、またはクッキー) によって異なります。explode(true/false) は、配列とオブジェクトが各配列項目またはオブジェクトプロパティに対して個別のパラメーターを生成するかどうかを指定します。
OpenAPIのシリアル化ルールは、RFC 6570で定義されているURIテンプレートパターンのサブセットに基づいています。ツール実装者は、以下で説明されているように、既存のURIテンプレートライブラリを使用してシリアル化を処理できます。
パスパラメータ
パスパラメーターは以下のstyle値をサポートします。
- simple – (デフォルト) カンマ区切りの値。
{param_name}URIテンプレートに対応します。 - label – ドットプレフィックスの値。ラベル拡張とも呼ばれます。
{.param_name}URIテンプレートに対応します。 - matrix – セミコロンプレフィックスの値。パススタイル拡張とも呼ばれます。
{;param_name}URIテンプレートに対応します。
デフォルトのシリアル化方法は、style: simple および explode: false です。パス /users/{id} が与えられた場合、パスパラメーター id は次のようにシリアル化されます。
| スタイル | 爆発する | URIテンプレート | プリミティブ値 id = 5 | 配列 id = [3, 4, 5] | オブジェクト id = {“role”: “admin”, “firstName”: “Alex”} |
|---|---|---|---|---|---|
| simple * | false * | /users/{id} | /users/5 | /users/3,4,5 | /users/role,admin,firstName,Alex |
| シンプル | 本当 | /users/{id*} | /users/5 | /users/3,4,5 | /users/role=admin,firstName=Alex |
| ラベル | 偽 | /users/{.id} | /users/.5 | /users/.3,4,5 | /users/.role,admin,firstName,Alex |
| ラベル | 本当 | /users/{.id*} | /users/.5 | /users/.3.4.5 | /users/.role=admin.firstName=Alex |
| マトリックス | 偽 | /users/{;id} | /users/;id=5 | /users/;id=3,4,5 | /users/;id=role,admin,firstName,Alex |
| マトリックス | 本当 | /users/{;id*} | /users/;id=5 | /users/;id=3;id=4;id=5 | /users/;role=admin;firstName=Alex |
- デフォルトのシリアル化方法
label および matrix スタイルは、パラメーター値にプレフィックスが付くため、/users{id} のような部分的なパスパラメーターで使用されることがあります。
クエリパラメータ
クエリパラメーターは以下のstyle値をサポートします。
- form – (デフォルト) アンパサンド区切りの値。フォームスタイルクエリ拡張とも呼ばれます。
{?param_name}URIテンプレートに対応します。 - spaceDelimited – スペース区切りの配列値。OpenAPI 2.0の
collectionFormat: ssvと同じです。非展開配列 (explode: false) にのみ効果があります。つまり、配列が単一のパラメーターである場合、arr=a b cのようにスペースが配列値を区切ります。 - pipeDelimited – パイプライン区切りの配列値。OpenAPI 2.0の
collectionFormat: pipesと同じです。非展開配列 (explode: false) にのみ効果があります。つまり、配列が単一のパラメーターである場合、arr=a|b|cのようにパイプが配列値を区切ります。 - deepObject – シンプルな非ネストオブジェクトは、
paramName[prop1]=value1¶mName[prop2]=value2&...としてシリアル化されます。ネストされたオブジェクトや配列の動作は未定義です。
デフォルトのシリアル化方法は、style: form および explode: true です。これは、OpenAPI 2.0のcollectionFormat: multiに対応します。クエリパラメーターidを持つパス/usersが与えられた場合、クエリ文字列は次のようにシリアル化されます。
| スタイル | 爆発する | URIテンプレート | プリミティブ値 id = 5 | 配列 id = [3, 4, 5] | オブジェクト id = {“role”: “admin”, “firstName”: “Alex”} |
|---|---|---|---|---|---|
| form * | true * | /users{?id*} | /users?id=5 | /users?id=3&id=4&id=5 | /users?role=admin&firstName=Alex |
| フォーム | 偽 | /users{?id} | /users?id=5 | /users?id=3,4,5 | /users?id=role,admin,firstName,Alex |
| スペース区切り | 本当 | /users{?id*} | 該当なし | /users?id=3&id=4&id=5 | 該当なし |
| スペース区切り | 偽 | 該当なし | 該当なし | /users?id=3%204%205 | 該当なし |
| パイプ区切り | 本当 | /users{?id*} | 該当なし | /users?id=3&id=4&id=5 | 該当なし |
| パイプ区切り | 偽 | 該当なし | 該当なし | /users?id=3|4|5 | 該当なし |
| ディープオブジェクト | 本当 | 該当なし | 該当なし | 該当なし | /users?id[role]=admin&id[firstName]=Alex |
* デフォルトのシリアル化方法
さらに、allowReservedキーワードは、パラメーター値内の予約文字:/?#[]@!$&'()*+,;=をそのまま送信することを許可するか、パーセントエンコードする必要があるかを指定します。デフォルトでは、allowReservedはfalseであり、予約文字はパーセントエンコードされます。例えば、/は%2F (または%2f) としてエンコードされるため、パラメーター値quotes/h2g2.txtはquotes%2Fh2g2.txtとして送信されます。
ヘッダーパラメータ
ヘッダーパラメーターは常にsimpleスタイル、つまりカンマ区切りの値を使用します。これは、{param_name} URIテンプレートに対応します。オプションのexplodeキーワードは、オブジェクトのシリアル化を制御します。X-MyHeaderという名前のリクエストヘッダーが与えられた場合、ヘッダー値は次のようにシリアル化されます。
| スタイル | 爆発する | URIテンプレート | プリミティブ値 X-MyHeader = 5 | 配列 X-MyHeader = [3, 4, 5] | オブジェクト X-MyHeader = {“role”: “admin”, “firstName”: “Alex”} |
|---|---|---|---|---|---|
| simple * | false * | {id} | X-MyHeader: 5 | X-MyHeader: 3,4,5 | X-MyHeader: role,admin,firstName,Alex |
| シンプル | 本当 | {id*} | X-MyHeader: 5 | X-MyHeader: 3,4,5 | X-MyHeader: role=admin,firstName=Alex |
- デフォルトのシリアル化方法
クッキーパラメーター
Cookieパラメーターは常にformスタイルを使用します。オプションのexplodeキーワードは、配列とオブジェクトのシリアル化を制御します。idという名前のCookieが与えられた場合、Cookie値は次のようにシリアル化されます。
| スタイル | 爆発する | URIテンプレート | プリミティブ値 id = 5 | 配列 id = [3, 4, 5] | オブジェクト id = {“role”: “admin”, “firstName”: “Alex”} |
|---|---|---|---|---|---|
| form * | true * | Cookie: id=5 | |||
| フォーム | 偽 | id={id} | Cookie: id=5 | Cookie: id=3,4,5 | Cookie: id=role,admin,firstName,Alex |
- デフォルトのシリアル化方法
シリアル化とRFC 6570
OpenAPIのシリアル化ルールは、RFC 6570で定義されているURIテンプレートのサブセットに基づいています。ツール実装者は、既存のURIテンプレートライブラリを使用してシリアル化を処理できます。パスとパラメーターの定義に基づいてURIテンプレートを構築する必要があります。以下の表は、OpenAPIキーワードがURIテンプレート修飾子にどのようにマッピングされるかを示しています。
| キーワード | URIテンプレート修飾子 |
|---|---|
style: simple | なし |
style: label | . プレフィックス |
style: matrix | ; プレフィックス |
style: form | ? または & プレフィックス (クエリ文字列内のパラメーターの位置によって異なります) |
style: pipeDelimited | ? または & プレフィックス (クエリ文字列内のパラメーターの位置によって異なります) – ただし、カンマ, の代わりにパイプ |を使用して配列値を結合します |
style: spaceDelimited | ? または & プレフィックス (クエリ文字列内のパラメーターの位置によって異なります) – ただし、カンマ, の代わりにスペースを使用して配列値を結合します |
explode: false | なし |
explode: true | * サフィックス |
allowReserved: false | なし |
allowReserved: true | + プレフィックス |
例えば、次のように定義されたクエリパラメーターmetadataを持つパス/users{id}を考えてみましょう。
1paths:2 # /users;id=3;id=4?metadata=true3 /users{id}:4 get:5 parameters:6 - in: path7 name: id8 required: true9 schema:10 type: array11 items:12 type: integer13 minItems: 114 style: matrix15 explode: true16 - in: query17 name: metadata18 schema:19 type: boolean20 # Using the default serialization for query parameters:21 # style=form, explode=false, allowReserved=false22 responses:23 '200':24 description: A list of usersパスパラメーターidは、explode修飾子を持つmatrixスタイルを使用しており、これは{;id*}テンプレートに対応します。クエリパラメーターmetadataはデフォルトのformスタイルを使用しており、これは{?metadata}テンプレートに対応します。完全なURIテンプレートは次のようになります。
1/users{;id*}{?metadata}クライアントアプリケーションは、このテンプレートと特定のパラメーター値に基づいてリクエストURLを生成するためにURIテンプレートライブラリを使用できます。
その他のシリアル化方法
style と explode は最も一般的なシリアル化方法をカバーしていますが、すべてではありません。より複雑なシナリオ (例えば、クエリ文字列内のJSON形式のオブジェクト) の場合は、contentキーワードを使用して、シリアル化形式を定義するメディアタイプを指定できます。詳細については、スキーマとコンテンツの比較を参照してください。
お探しのものが見つかりませんでしたか？ コミュニティに質問する
間違いを見つけましたか？ お知らせください