パラメータのシリアル化

注

OAS 3 このガイドはOpenAPI 3.0用です。

シリアル化とは、データ構造やオブジェクトの状態を、後で送信および再構築できる形式に変換することです。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&paramName[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}を考えてみましょう。

paths:
  # /users;id=3;id=4?metadata=true
  /users{id}:
    get:
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: array
            items:
              type: integer
            minItems: 1
          style: matrix
          explode: true
        - in: query
          name: metadata
          schema:
            type: boolean
          # Using the default serialization for query parameters:
          # style=form, explode=false, allowReserved=false
      responses:
        '200':
          description: A list of users

パスパラメーターidは、explode修飾子を持つmatrixスタイルを使用しており、これは{;id*}テンプレートに対応します。クエリパラメーターmetadataはデフォルトのformスタイルを使用しており、これは{?metadata}テンプレートに対応します。完全なURIテンプレートは次のようになります。

/users{;id*}{?metadata}

クライアントアプリケーションは、このテンプレートと特定のパラメーター値に基づいてリクエストURLを生成するためにURIテンプレートライブラリを使用できます。

その他のシリアル化方法

style と explode は最も一般的なシリアル化方法をカバーしていますが、すべてではありません。より複雑なシナリオ (例えば、クエリ文字列内のJSON形式のオブジェクト) の場合は、contentキーワードを使用して、シリアル化形式を定義するメディアタイプを指定できます。詳細については、スキーマとコンテンツの比較を参照してください。

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