參數序列化

序列化是指將資料結構或物件狀態轉換為可以傳輸並在稍後重建的格式。OpenAPI 3.0 支援操作參數（路徑、查詢、標頭和 Cookie）中的陣列和物件，並讓您可以指定如何序列化這些參數。序列化方法由 style 和 explode 關鍵字定義

style 定義如何分隔多個值。可能的樣式取決於參數位置 – 路徑、查詢、標頭或 Cookie。
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
simple	true	/users/{id*}	/users/5	/users/3,4,5	/users/role=admin,firstName=Alex
label	false	/users/{.id}	/users/.5	/users/.3,4,5	/users/.role,admin,firstName,Alex
label	true	/users/{.id*}	/users/.5	/users/.3.4.5	/users/.role=admin.firstName=Alex
matrix	false	/users/{;id}	/users/;id=5	/users/;id=3,4,5	/users/;id=role,admin,firstName,Alex
matrix	true	/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。假設路徑為 /users，且查詢參數為 id，則查詢字串的序列化方式如下

樣式	展開	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
form	false	/users{?id}	/users?id=5	/users?id=3,4,5	/users?id=role,admin,firstName,Alex
spaceDelimited	true	/users{?id*}	不適用	/users?id=3&id=4&id=5	不適用
spaceDelimited	false	不適用	不適用	/users?id=3%204%205	不適用
pipeDelimited	true	/users{?id*}	不適用	/users?id=3&id=4&id=5	不適用
pipeDelimited	false	不適用	不適用	/users?id=3\|4\|5	不適用
deepObject	true	不適用	不適用	不適用	/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
simple	true	{id*}	X-MyHeader: 5	X-MyHeader: 3,4,5	X-MyHeader: role=admin,firstName=Alex

預設序列化方法

Cookie 參數一律使用 form 樣式。一個可選的 explode 關鍵字控制陣列和物件的序列化。假設 Cookie 名稱為 id，則 Cookie 值序列化如下

樣式	展開	URI 範本	基本值 id = 5	陣列 id = [3, 4, 5]	物件 id = {“role”: “admin”, “firstName”: “Alex”}
form *	true *		Cookie: id=5
form	false	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`	`+` 前綴

例如，考慮路徑 /users{id} 以及查詢參數 metadata，其定義如下

1
paths:
2
  # /users;id=3;id=4?metadata=true
3
  /users{id}:
4
    get:
5
      parameters:
6
        - in: path
7
          name: id
8
          required: true
9
          schema:
10
            type: array
11
            items:
12
              type: integer
13
            minItems: 1
14
          style: matrix
15
          explode: true
16
        - in: query
17
          name: metadata
18
          schema:
19
            type: boolean
20
          # Using the default serialization for query parameters:
21
          # style=form, explode=false, allowReserved=false
22
      responses:
23
        '200':
24
          description: A list of users

路徑參數 id 使用 matrix 樣式以及 explode 修飾符，這對應於 {;id*} 樣板。查詢參數 metadata 使用預設的 form 樣式，這對應於 {?metadata} 樣板。完整的 URI 樣板將如下所示

1
/users{;id*}{?metadata}

然後，用戶端應用程式可以使用 URI 樣板程式庫，根據此樣板和特定的參數值來產生請求 URL。

其他序列化方法

style 和 explode 涵蓋了最常見的序列化方法，但並非全部。對於更複雜的情況（例如，查詢字串中的 JSON 格式物件），您可以使用 content 關鍵字，並指定定義序列化格式的媒體類型。如需更多資訊，請參閱schema vs content。

找不到您要找的內容嗎？請教社群
發現錯誤？請告訴我們