OpenAPI 規範

版本 3.1.1

本文件中，關鍵字「必須（MUST）」、「不得（MUST NOT）」、「必要（REQUIRED）」、「應（SHALL）」、「不得（SHALL NOT）」、「應該（SHOULD）」、「不應該（SHOULD NOT）」、「建議（RECOMMENDED）」、「不建議（NOT RECOMMENDED）」、「可以（MAY）」和「選擇性（OPTIONAL）」的解釋，必須如 BCP 14 RFC2119 RFC8174 中所述，而且僅限於以全部大寫字母顯示時，如這裡所示。

本文件依據 Apache 授權條款 2.0 版 授權。

簡介

OpenAPI 規範 (OAS) 定義了一種標準的、與語言無關的 HTTP API 介面，讓人類和電腦都能夠在不存取原始程式碼、文件或透過網路流量檢查的情況下，發現並了解服務的功能。如果定義得當，消費者可以透過最少的實作邏輯來理解遠端服務並與之互動。

然後，文件產生工具可以使用 OpenAPI 描述來顯示 API，程式碼產生工具可以使用 OpenAPI 描述以各種程式語言產生伺服器和用戶端，以及測試工具和許多其他使用案例。

如需 OpenAPI 使用範例和其他文件，請造訪 [[?OpenAPI-Learn]]。

如需 OpenAPI 倡議發布的擴充註冊表和其他規範，以及本規範的權威呈現方式，請造訪 spec.openapis.org。

定義

OpenAPI 描述

OpenAPI 描述 (OAD) 正式描述 API 的介面及其語意。它由一個進入文件組成，該文件必須是 OpenAPI 文件，以及其任何/所有參考的文件。OAD 使用並符合 OpenAPI 規範，並且必須至少包含一個路徑欄位、元件欄位或Webhooks欄位。

OpenAPI 文件

OpenAPI 文件是一個符合 OpenAPI 規範的單一 JSON 或 YAML 文件。與 OAS 3.*.* 相容的 OpenAPI 文件包含一個必要的openapi欄位，該欄位指定其使用的 OAS 版本。

綱要

「綱要」是對語法和結構的正式描述。本文件充當 OpenAPI 規範格式的綱要；基於本文件且非權威性的 JSON 綱要也提供在 spec.openapis.org 上，僅供參考。此規範也使用綱要物件形式的綱要。

物件

大寫的「物件」一詞是指本文件中按章節標題命名的任何物件。

路徑範本

路徑範本是指使用以大括號 ({}) 分隔的範本表達式，將 URL 路徑的一部分標記為可使用路徑參數取代。

路徑中的每個範本表達式都必須對應於路徑項目本身和/或每個路徑項目的作業中包含的路徑參數。如果路徑項目為空，例如由於 ACL 限制，則不需要符合的路徑參數。

這些路徑參數的值不得包含 RFC3986 所述的任何未逸出的「通用語法」字元：正斜線 (/)、問號 (?) 或井號 (#)。

媒體類型

媒體類型定義分散在多個資源中。媒體類型定義應符合 RFC6838。

一些可能的媒體類型定義範例

  text/plain; charset=utf-8
  application/json
  application/vnd.github+json
  application/vnd.github.v3+json
  application/vnd.github.v3.raw+json
  application/vnd.github.v3.text+json
  application/vnd.github.v3.html+json
  application/vnd.github.v3.full+json
  application/vnd.github.v3.diff
  application/vnd.github.v3.patch

HTTP 狀態碼

HTTP 狀態碼用於指示執行作業的狀態。狀態碼應從IANA 狀態碼註冊表中可用的狀態碼中選取。

大小寫敏感度

由於 OpenAPI 規範中的大多數欄位名稱和值都是區分大小寫的，因此本文件力求指出任何不區分大小寫的名稱和值。但是，直接對應到 HTTP 概念的欄位名稱和值的大小寫敏感度，遵循 HTTP 的大小寫敏感度規則，即使本文件未對每個概念進行註記。

未定義和實作定義的行為

本規範認為某些情況具有未定義或實作定義的行為。

描述為未定義的行為，至少在某些情況下，可能會導致與規範不符的結果。當無法或不切實際地偵測矛盾時，會使用此描述。為了歷史原因，實作可以支援未定義的狀況，包括先前版本的規範中的模糊文字。此支援在許多情況下可能會產生正確的結果，但不建議依賴它，因為無法保證它可以在所有工具或未來規範版本中使用，即使這些版本在其他方面與此版本嚴格相容。

描述為實作定義的行為，允許實作選擇數種不同但符合要求的實作方法。此文件闡明了 API 描述作者為了最大化互操作性而建議避免的模糊要求。與未定義的行為不同，如果並且只有在可以保證所有相關工具都支援相同的行為時，才可以安全地依賴實作定義的行為。

規範

版本

OpenAPI 規範使用 major.minor.patch 版本方案進行版本控制。版本字串的 major.minor 部分（例如 3.1）應指定 OAS 功能集。.patch 版本解決本文件中的錯誤或提供說明，而不是功能集。支援 OAS 3.1 的工具應與所有 OAS 3.1.* 版本相容。工具不應考慮修補程式版本，例如 3.1.0 和 3.1.1 之間沒有區別。

有時，OAS 的 minor 版本可能會進行不向後相容的變更，其影響被認為相對於提供的優勢較小。

格式

符合 OpenAPI 規範的 OpenAPI 文件本身是一個 JSON 物件，可以用 JSON 或 YAML 格式表示。

例如，如果欄位具有陣列值，則將使用 JSON 陣列表示法

{
  "field": [1, 2, 3]
}

規格中的所有欄位名稱皆為區分大小寫。這包括所有用作映射中鍵值的欄位，除非明確註明鍵值為不區分大小寫。

綱要 揭示了兩種欄位類型：固定欄位，具有宣告的名稱；以及模式欄位，具有宣告的欄位名稱模式。

模式欄位在其所包含的物件中必須具有唯一的名稱。

為了保留 YAML 和 JSON 格式之間的往返轉換能力，建議使用 YAML 版本 1.2，並加上一些額外的約束。

• 標籤必須限制為 YAML 的 JSON 綱要規則集所允許的標籤，該規則集定義了 YAML 語法的子集，並且與 [[JSON-Schema-2020-12|JSON 綱要]] 無關。
• YAML 映射中使用的鍵值必須限制為純量字串，如 YAML Failsafe 綱要規則集所定義。

注意：雖然 API 可以使用 YAML 或 JSON 格式的 OpenAPI 描述來描述，但 API 請求和回應主體以及其他內容不一定必須是 JSON 或 YAML。

OpenAPI 描述結構

OpenAPI 描述 (OAD) 可以由單一的 JSON 或 YAML 文件組成，也可以由作者自行決定分割成多個相互連接的部分。在後一種情況下，會使用 參考物件、路徑項目物件 和 綱要物件 的 $ref 欄位，以及 連結物件 的 operationRef 欄位，和 辨別器物件 的 mapping 欄位的 URI 形式，來識別所參考的元素。

在多文件 OAD 中，包含開始解析的 OpenAPI 物件的文件稱為該 OAD 的起始文件。

建議將 OAD 的起始文件命名為：openapi.json 或 openapi.yaml。

解析文件

為了正確處理 綱要物件，OAS 3.1 繼承了 JSON 綱要規格草案 2020-12 的解析要求，並根據 API 描述 URI 中的相對參考 中的規定對基準 URI 進行了適當的修改。

這包括在判定綱要物件參考無法解析之前，必須先解析完整文件，以便偵測可能提供參考目標或影響適當基準 URI 判定的關鍵字。

實作可以透過下列任何方式支援完整文件解析

• 使用媒體類型偵測 OpenAPI 或 JSON 綱要文件
• 透過根 openapi 欄位偵測 OpenAPI 文件
• 透過偵測關鍵字或以其他方式依照 JSON 綱要規格成功解析文件來偵測 JSON 綱要文件
• 根據參考的預期類型，偵測在其根部包含可參考物件的文件
• 允許使用者設定可能因參考非根物件而載入的文件類型

在解析 OpenAPI 內容的參考片段時，不考慮其所在文件其餘內容的實作，將會遺失會改變參考目標意義和行為的關鍵字。特別是，未能考慮會改變基準 URI 的關鍵字，會因導致參考解析為非預期的 URI 而引入安全性風險，並產生無法預測的結果。雖然某些實作因本規格過去版本的需求而支援這種解析，但在 3.1 版中，將片段獨立解析的結果是未定義的，並且很可能與本規格的要求相矛盾。

雖然有可能建構某些 OpenAPI 描述，以確保它們在將參考解析為獨立片段時能正確運作，但不建議依賴此行為。本規格並未明確列舉此類行為安全的條件，並且不保證在任何未來的 OAS 版本中都能持續安全。

解析 OAS 內容片段的特殊情況是，如果此類片段嵌入在另一種格式中，則相對於 OAS，將其稱為嵌入格式。請注意，OAS 本身是相對於 JSON 綱要的嵌入格式，JSON 綱要以綱要物件的形式嵌入。嵌入格式有責任定義如何解析嵌入的內容，並且未記錄支援嵌入格式的 OAS 實作無法預期能夠正確解析嵌入的 OAS 內容。

結構互通性

OAD 中的 JSON 或 YAML 物件會根據其內容解釋為特定的物件（例如 操作物件、回應物件、參考物件 等）。根據參考的安排方式，可以將給定的 JSON 或 YAML 物件解釋為多個不同的內容。

• 作為 起始文件的根物件，該物件始終被解釋為 OpenAPI 物件
• 作為文件中由其父物件所暗示的物件類型
• 作為參考目標，其物件類型與參考來源的內容相符

如果同一個 JSON/YAML 物件被解析多次，並且相應的內容要求將其解析為不同的物件類型，則產生的行為將是實作定義的，並且如果偵測到則可能會被視為錯誤。例如，在預期為路徑項目物件的情況下，參考 #/components/schemas 下的空白綱要物件，因為空白物件對兩種型別都有效。為了獲得最大的互通性，建議 OpenAPI 描述作者避免這種情況。

解析隱含的連線

本規格的幾個功能需要解析與 OpenAPI 描述 (OAD) 的其他部分的非 URI 連線。

這些連線在單文件 OAD 中會明確解析，但在多文件 OAD 中的解析過程是實作定義的，並遵守本節所述的約束。在某些情況下，可以使用明確的 URI 替代方案，建議 OAD 作者始終使用該替代方案。

來源	目標	替代方案
安全需求物件 {name}	安全配置物件 在 組件物件下的名稱	不適用
辨別器物件 mapping (隱含或明確的名稱語法)	綱要物件 在組件物件下的名稱	mapping (明確的 URI 語法)
操作物件 tags	標籤物件 name (在 OpenAPI 物件 的 tags 陣列中)	不適用
連結物件 operationId	路徑項目物件 operationId	operationRef

第五個隱含連線包括將 路徑物件 的模板 URL 路徑附加到適當的 伺服器物件 的 url 欄位。這是明確的，因為只有起始文件的路徑物件才會將 URL 提供給描述的 API。

建議在解析任何連結物件 operationId 時，考慮來自所有已解析文件的所有操作物件。這需要在判定 operationId 無法解析之前，先解析所有參考的文件。

安全需求物件和辨別器物件中的隱含連線依賴於組件名稱，組件名稱是指在組件物件的適當類型子物件中保存組件的屬性名稱。例如，#/components/schemas/Foo 處的綱要物件的組件名稱為 Foo。操作物件中 tags 的隱含連線使用標籤物件的 name 欄位，該欄位（與組件物件一樣）位於根 OpenAPI 物件下。這表示解析組件名稱和標籤名稱都依賴於從正確的 OpenAPI 物件開始。

為了從參考 (非起始) 文件解析組件和標籤名稱連線，建議工具從起始文件解析，而不是從目前文件解析。這允許將安全配置物件和標籤物件定義在 API 的部署資訊 (伺服器物件的最上層陣列) 旁邊，並將其視為參考文件存取的介面。

介面方法也適用於辨別器物件和綱要物件，但是也可以使用 mapping 的相對 URI 參考語法，在單一文件中保留辨別器物件的行為。

安全需求物件或操作物件的 tags 欄位沒有基於 URI 的替代方案。預期在未來的版本中會解決這些限制。

請參閱 附錄 F：在參考文件中解析安全需求，以了解可能的解析範例，包括本節建議的解析範例。辨別器物件非 URI 映射和操作物件的 tags 欄位的行為遵循相同的原則。

請注意，隱含連線解析的任何方面都不會變更 URI 的解析方式，或限制其可能的目標。

資料類型

OAS 中的資料類型基於 JSON 綱要驗證規格草案 2020-12 定義的類型：「null」、「boolean」、「object」、「array」、「number」、「string」或「integer」。模型使用 綱要物件 定義，它是 JSON 綱要規格草案 2020-12 的超集。

JSON Schema 的關鍵字和 format 值作用於 JSON「實例」，這些實例可能是六種 JSON 資料類型之一：「null」、「boolean」、「object」、「array」、「number」或「string」，其中某些關鍵字和格式僅適用於特定類型。例如，pattern 關鍵字和 date-time 格式僅適用於字串，並將其他五種類型的任何實例視為自動有效。這表示 JSON Schema 的關鍵字和格式並不隱含要求預期的類型。請使用 type 關鍵字來明確限制類型。

請注意，為了方便起見，type 關鍵字允許 "integer" 作為值，但關鍵字和格式的適用性並不將整數視為與其他數字不同的 JSON 類型，因為 [[RFC7159|JSON]] 本身並未區分這一點。由於沒有明確的 JSON 整數類型，JSON Schema 在數學上定義了整數。這表示 1 和 1.0 是等價的，並且都被視為整數。

資料類型格式

如 JSON Schema 驗證規範所定義，資料類型可以有一個可選的修飾符關鍵字：format。如該規範所述，format 預設被視為非驗證註解；驗證 format 的能力因實作而異。

OpenAPI Initiative 也為 OAS 使用者和其他規範定義的格式託管了一個 格式註冊表。對任何註冊格式的支援是嚴格的「可選」項目，對一種註冊格式的支援並不表示對任何其他格式的支援。

未附帶 format 關鍵字的類型遵循 JSON Schema 中的類型定義。不識別特定 format 的工具「可以」還原為僅使用 type，就像沒有指定 format 一樣。為了進行 JSON Schema 驗證，每個格式都應指定其適用的 JSON 資料類型集。在此註冊表中，這些類型顯示在「JSON 資料類型」欄中。

OAS 定義的格式如下

格式	JSON 資料類型	註解
int32	number	帶符號 32 位元
int64	number	帶符號 64 位元 (又稱 long)
float	number
double	number
password	string	提示以模糊值。

如資料類型下所述，type: number 和 type: integer 在資料模型中都被視為數字。

處理二進位資料

OAS 可以描述原始或編碼二進位資料。

• 當允許未編碼的二進位資料時，例如當將二進位酬載作為整個 HTTP 訊息主體發送，或作為允許二進位部分的 multipart/* 酬載的一部分時，會使用原始二進位。
• 當二進位資料嵌入僅文字格式中時，例如 application/json 或 application/x-www-form-urlencoded（作為訊息主體或在 URL 查詢字串中），會使用編碼二進位。

在下表中顯示如何使用 Schema Object 關鍵字處理二進位資料時，我們使用 image/png 作為範例二進位媒體類型。任何二進位媒體類型（包括 application/octet-stream）都足以表示二進位內容。

關鍵字	原始	編碼	註解
type	省略	string	原始二進位在 type 之外
contentMediaType	image/png	image/png	如果冗餘，有時可以省略（請參閱下方）
contentEncoding	省略	base64 或 base64url	允許其他編碼 允許

請注意，contentEncoding 所指示的編碼（為了將資料表示為 7 位元 ASCII 文字而膨脹資料大小）與 HTTP 的 Content-Encoding 標頭無關，後者表示訊息主體是否經過壓縮以及如何壓縮，並且在發生本節中描述的所有內容序列化之後才套用。由於 HTTP 允許未編碼的二進位訊息主體，因此沒有標準化的 HTTP 標頭來表示整個訊息主體的 base64 或類似編碼。

使用 base64url 的 contentEncoding 可確保 URL 編碼（如查詢字串和 application/x-www-form-urlencoded 類型的訊息主體中所需）不需要進一步編碼任何已編碼的二進位資料部分。

如果媒體類型已設定，則 contentMediaType 關鍵字是冗餘的

• 作為 MediaType Object 的索引鍵
• 在 Encoding Object 的 contentType 欄位中

如果 Schema Object 將由非 OAS 感知的 JSON Schema 實作處理，即使它是冗餘的，包含 contentMediaType 也可能很有用。但是，如果 contentMediaType 與相關的媒體類型物件或編碼物件衝突，則「應」忽略 contentMediaType。

maxLength 關鍵字「可以」用於設定串流酬載長度的預期上限。此關鍵字可以套用於字串資料（包括編碼的二進位資料）或未編碼的二進位資料。對於未編碼的二進位資料，長度是八位元組的數量。

從 OAS 3.0 移轉二進位描述

下表顯示如何從 OAS 3.0 二進位資料描述移轉，並繼續使用 image/png 作為範例二進位媒體類型

OAS < 3.1	OAS 3.1	註解
type: string format: binary	contentMediaType: image/png	如果冗餘，可以省略，通常會導致空的 Schema Object
type: string format: byte	type: string contentMediaType: image/png contentEncoding: base64	請注意，可以使用 base64url 來避免重新編碼 base64 字串以使其成為 URL 安全的

富文本格式

在整個規格中，description 欄位被註記為支援 CommonMark markdown 格式。在 OpenAPI 工具呈現富文本的地方，它「必須」至少支援 CommonMark 0.27 所述的 markdown 語法。工具「可以」選擇忽略某些 CommonMark 或擴充功能，以解決安全性問題。

雖然將 CommonMark 0.27 定為最低要求意味著工具「可以」選擇在其之上實作擴充功能，但請注意，任何此類擴充功能都按定義為實作定義，並且將不可互通。OpenAPI 描述作者「應」考慮僅提供最低支援的工具將如何呈現使用此類擴充功能的文字。

API 描述 URI 中的相對參照

在 OpenAPI 描述中用作參照，或用於外部文件或許可證等其他補充資訊的 URI 會解析為識別碼，並在此規格中描述為 URI。如 剖析文件下所述，此規格繼承了 JSON Schema 規格草案 2020-12 對於載入文件並將其與預期 URI 關聯的要求，這些 URI 可能與其目前位置不符。此功能可用於在開發或測試環境中工作而無需變更 URI，以及在限制性網路組態或安全性原則內工作。

請注意，由於歷史原因，某些 URI 欄位被命名為 url，但這些欄位的描述性文字使用了正確的「URI」術語。

除非另有指定，否則所有作為 URI 的欄位「可以」是 RFC3986 所定義的相對參照。

Schema Object 中的相對參照（包括任何顯示為 $id 值的參照）使用最近的父 $id 作為基底 URI，如 JSON Schema 規格草案 2020-12 所述。

其他物件中的相對 URI 參照，以及沒有父 schema 包含 $id 的 Schema Object 中的相對 URI 參照「必須」使用參照文件的基底 URI 解析，該基底 URI 根據 [[RFC3986]] 第 5.1.2 – 5.1.4 節決定。實際上，這通常是文件的擷取 URI，它「可以」根據其目前的實際位置或使用者提供的預期位置來決定。

如果 URI 包含片段識別碼，則應根據參照文件的片段解析機制解析片段。如果參照文件的表示是 JSON 或 YAML，則片段識別碼「應」根據 RFC6901 解釋為 JSON 指標。

CommonMark 超連結中的相對參照在其呈現的內容中解析，這可能與 API 描述的內容不同。

API URL 中的相對參照

API 端點按定義以位置的形式存取，並在此規格中描述為 URL。

除非另有指定，否則所有作為 URL 的欄位「可以」是 RFC3986 所定義的相對參照。除非另有指定，否則相對參照使用 Server Object 中定義的 URL 作為基底 URL 解析。請注意，這些本身「可以」相對於參照文件。

綱要

本節描述 OpenAPI 描述格式的結構。本文是格式的唯一規範描述。JSON Schema 託管在 spec.openapis.org 上，僅供參考。如果 JSON Schema 與本節不同，則「必須」將本節視為權威。

在以下描述中，如果欄位未明確宣告為必要或使用 MUST 或 SHALL 描述，則可以將其視為選用。

OpenAPI 物件

這是 OpenAPI 描述的根物件。

固定欄位

欄位名稱	類型	描述
openapi	string	必要。此字串「必須」是 OpenAPI 文件使用的 OpenAPI 規格的版本號碼。工具「應」使用 openapi 欄位來解釋 OpenAPI 文件。這與 API info.version 字串無關。
info	資訊物件	必要。提供有關 API 的中繼資料。工具「可以」根據需要使用中繼資料。
jsonSchemaDialect	string	此 OAS 文件中包含的 Schema Object 中 $schema 關鍵字的預設值。這「必須」採用 URI 的形式。
servers	[伺服器物件]	伺服器物件的陣列，提供目標伺服器的連線資訊。如果未提供 servers 欄位，或是一個空的陣列，則預設值會是 伺服器物件，其 url 值為 /。
paths	路徑物件	API 可用的路徑和操作。
webhooks	Map[string, 路徑項目物件]	作為此 API 一部分可能接收，且 API 消費者可選擇實作的傳入 Webhook。與 callbacks 功能密切相關，本節描述了由 API 呼叫以外的其他方式起始的請求，例如透過帶外註冊。索引鍵名稱是每個 Webhook 的唯一字串，而（可選的參考）路徑項目物件描述了可能由 API 提供者起始的請求以及預期的回應。提供了一個範例。
components	元件物件	一個用於存放 OpenAPI 描述中各種物件的元素。
security	[安全需求物件]	宣告 API 中可使用的安全機制。值的列表包含可使用的替代安全需求物件。只需滿足一個安全需求物件即可授權請求。個別操作可以覆寫此定義。列表可能不完整，甚至可以是空的或不存在。為了使安全性明確為可選，可以在陣列中包含一個空的安全需求 ({})。
tags	[標籤物件]	OpenAPI 描述使用的帶有額外元數據的標籤列表。標籤的順序可用於反映解析工具的順序。並非所有 操作物件 使用的標籤都必須宣告。未宣告的標籤可以隨機組織或基於工具的邏輯。列表中每個標籤名稱都必須是唯一的。
externalDocs	外部文件物件	額外的外部文件。

此物件可以透過規格擴充來擴充。

資訊物件

此物件提供關於 API 的元數據。如果需要，客戶端可以使用此元數據，並且可以在編輯或文件產生工具中顯示，以方便使用。

固定欄位

欄位名稱	類型	描述
title	string	必要。API 的標題。
summary	string	API 的簡短摘要。
description	string	API 的描述。可以使用 CommonMark 語法 來表示豐富的文字。
termsOfService	string	API 服務條款的 URI。這必須採用 URI 的形式。
contact	聯絡方式物件	公開 API 的聯絡資訊。
license	授權物件	公開 API 的授權資訊。
version	string	必要。OpenAPI 文件的版本（與 OpenAPI 規格版本或所描述 API 的版本或 OpenAPI 描述的版本不同）。

此物件可以透過規格擴充來擴充。

Info 物件範例

{
  "title": "Example Pet Store App",
  "summary": "A pet store manager.",
  "description": "This is an example server for a pet store.",
  "termsOfService": "https://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "https://www.example.com/support",
    "email": "[email protected]"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

title: Example Pet Store App
summary: A pet store manager.
description: This is an example server for a pet store.
termsOfService: https://example.com/terms/
contact:
  name: API Support
  url: https://www.example.com/support
  email: [email protected]
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

聯絡方式物件

公開 API 的聯絡資訊。

固定欄位

欄位名稱	類型	描述
name	string	聯絡人/組織的識別名稱。
url	string	聯絡資訊的 URI。這必須採用 URI 的形式。
email	string	聯絡人/組織的電子郵件地址。這必須採用電子郵件地址的形式。

此物件可以透過規格擴充來擴充。

聯絡方式物件範例

{
  "name": "API Support",
  "url": "https://www.example.com/support",
  "email": "[email protected]"
}

name: API Support
url: https://www.example.com/support
email: [email protected]

授權物件

公開 API 的授權資訊。

固定欄位

欄位名稱	類型	描述
name	string	必要。用於 API 的授權名稱。
identifier	string	API 的 SPDX 授權表達式。identifier 欄位與 url 欄位互斥。
url	string	用於 API 的授權 URI。這必須採用 URI 的形式。url 欄位與 identifier 欄位互斥。

此物件可以透過規格擴充來擴充。

授權物件範例

{
  "name": "Apache 2.0",
  "identifier": "Apache-2.0"
}

name: Apache 2.0
identifier: Apache-2.0

伺服器物件

表示伺服器的物件。

固定欄位

欄位名稱	類型	描述
url	string	必要。目標主機的 URL。此 URL 支援伺服器變數，並且可以是相對的，表示主機位置相對於提供包含伺服器物件的文件的位置。當變數在 {大括號} 中命名時，將進行變數替換。
description	string	描述由 URL 指定的主機的可選字串。可以使用 CommonMark 語法 來表示豐富的文字。
variables	Map[string, 伺服器變數物件]	變數名稱及其值之間的對應。該值用於伺服器 URL 範本中的替換。

此物件可以透過規格擴充來擴充。

伺服器物件範例

單個伺服器將描述為

{
  "url": "https://development.gigantic-server.com/v1",
  "description": "Development server"
}

url: https://development.gigantic-server.com/v1
description: Development server

以下展示了如何描述多個伺服器，例如，在 OpenAPI 物件的 servers 中

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

servers:
  - url: https://development.gigantic-server.com/v1
    description: Development server
  - url: https://staging.gigantic-server.com/v1
    description: Staging server
  - url: https://api.gigantic-server.com/v1
    description: Production server

以下展示了如何將變數用於伺服器設定

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "A user-specific subdomain. Use `demo` for a free sandbox environment."
        },
        "port": {
          "enum": ["8443", "443"],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

servers:
  - url: https://{username}.gigantic-server.com:{port}/{basePath}
    description: The production API server
    variables:
      username:
        # note! no enum here means it is an open value
        default: demo
        description: A user-specific subdomain. Use `demo` for a free sandbox environment.
      port:
        enum:
          - '8443'
          - '443'
        default: '8443'
      basePath:
        # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
        default: v2

伺服器變數物件

表示用於伺服器 URL 範本替換的伺服器變數的物件。

固定欄位

欄位名稱	類型	描述
enum	[string]	如果替換選項來自有限的集合，則使用的字串值列舉。陣列不得為空。
default	string	必要。用於替換的預設值，如果未提供替代值，則應發送此值。如果定義了 enum，則該值必須存在於 enum 的值中。請注意，此行為與 架構物件 的 default 關鍵字不同，後者記錄接收者的行為，而不是將值插入到數據中。
description	string	伺服器變數的可選描述。可以使用 CommonMark 語法 來表示豐富的文字。

此物件可以透過規格擴充來擴充。

元件物件

持有 OAS 不同方面的可重用物件集合。除非從元件物件外部明確引用，否則元件物件內定義的所有物件對 API 沒有影響。

固定欄位

欄位名稱	類型	描述
schemas	Map[string, 架構物件]	一個用於存放可重用的架構物件的物件。
responses	Map[string, 回應物件 | 參考物件]	一個用於存放可重用的回應物件的物件。
parameters	Map[string, 參數物件 | 參考物件]	一個用於存放可重用的參數物件的物件。
examples	Map[string, 範例物件 | 參考物件]	一個用於存放可重用的範例物件的物件。
requestBodies	Map[string, 請求主體物件 | 參考物件]	一個用於存放可重用的請求主體物件的物件。
headers	Map[string, 標頭物件 | 參考物件]	一個用於存放可重用的標頭物件的物件。
securitySchemes	Map[string, 安全方案物件 | 參考物件]	一個用於存放可重用的安全方案物件的物件。
links	Map[string, 連結物件 | 參考物件]	一個用於存放可重用的連結物件的物件。
callbacks	Map[string, 回調物件 | 參考物件]	一個用於存放可重用的回調物件的物件。
pathItems	Map[string, 路徑項目物件]	一個用於存放可重用的路徑項目物件的物件。

此物件可以透過規格擴充來擴充。

上面宣告的所有固定欄位都是物件，必須使用符合以下正規表達式的鍵：^[a-zA-Z0-9\.\-_]+$。

欄位名稱範例

User
User_1
User_Name
user-name
my.org.User

元件物件範例

"components": {
  "schemas": {
    "GeneralError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api-key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "https://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}

components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api-key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

路徑物件

持有個別端點及其操作的相對路徑。路徑會附加到 伺服器物件 中的 URL，以建構完整的 URL。由於存取控制列表 (ACL) 約束，路徑物件可能為空。

模式化欄位

欄位模式	類型	描述
/{path}	路徑項目物件	個別端點的相對路徑。欄位名稱必須以正斜線 (/) 開頭。路徑會附加（不進行相對 URL 解析）到來自 伺服器物件 的 url 欄位的展開 URL，以建構完整的 URL。允許路徑範本化。匹配 URL 時，具體（非範本化）路徑會在其範本化對應項之前匹配。具有相同層次結構但範本化名稱不同的範本化路徑不得存在，因為它們是相同的。在有歧義的匹配情況下，由工具決定使用哪一個。

此物件可以透過規格擴充來擴充。

路徑範本化匹配

假設以下路徑，如果使用具體定義 /pets/mine，它將首先被匹配

  /pets/{petId}
  /pets/mine

以下路徑被視為相同且無效

  /pets/{petId}
  /pets/{name}

以下可能會導致不明確的解析

  /{entity}/me
  /books/{id}

路徑物件範例

{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}

/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'

路徑項目物件

描述單個路徑上可用的操作。由於ACL 約束，路徑項目可能為空。路徑本身仍然暴露給文件檢視器，但他們不會知道有哪些操作和參數可用。

固定欄位

欄位名稱	類型	描述
$ref	string	允許此路徑項目的參考定義。該值必須採用 URI 的形式，並且參考的結構必須採用路徑項目物件的形式。如果路徑項目物件欄位同時出現在已定義的物件和參考的物件中，則行為未定義。請參閱解析API 描述 URI 中的相對參考的規則。 注意：$ref 與相鄰屬性的行為可能會在此規格的未來版本中更改，使其更接近參考物件的行為。
summary	string	適用於此路徑中所有操作的可選字串摘要。
description	string	適用於此路徑中所有操作的可選字串描述。可以使用 CommonMark 語法 來表示豐富的文字。
get	操作物件	此路徑上 GET 操作的定義。
put	操作物件	此路徑上 PUT 操作的定義。
post	操作物件	此路徑上 POST 操作的定義。
delete	操作物件	此路徑上 DELETE 操作的定義。
options	操作物件	此路徑上 OPTIONS 操作的定義。
head	操作物件	此路徑上 HEAD 操作的定義。
patch	操作物件	此路徑上 PATCH 操作的定義。
trace	操作物件	此路徑上 TRACE 操作的定義。
servers	[伺服器物件]	用於服務此路徑中所有操作的替代 servers 陣列。如果在OpenAPI 物件層級指定了 servers 陣列，它將被此值覆寫。
parameters	[參數物件 | 參考物件]	適用於此路徑下所有操作的參數列表。這些參數可以在操作層級被覆寫，但不能在那裡被移除。此列表**必須不**包含重複的參數。一個獨特的參數是由 名稱 和 位置 的組合所定義。此列表可以使用 參考物件 來連結到在 OpenAPI 物件的 components.parameters 中定義的參數。

此物件可以透過規格擴充來擴充。

路徑項目物件範例

{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "error payload",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*':
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        text/html:
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
  - name: id
    in: path
    description: ID of pet to use
    required: true
    schema:
      type: array
      items:
        type: string
    style: simple

操作物件

描述路徑上單一 API 操作。

固定欄位

欄位名稱	類型	描述
tags	[string]	用於 API 文件控制的標籤列表。標籤可用於按資源或其他限定符對操作進行邏輯分組。
summary	string	操作內容的簡短摘要。
description	string	操作行為的詳細說明。可以使用 CommonMark 語法 來呈現豐富的文字格式。
externalDocs	外部文件物件	此操作的額外外部文件。
operationId	string	用於識別操作的唯一字串。在 API 中描述的所有操作中，id **必須**是唯一的。operationId 值是**區分大小寫的**。工具和函式庫可以使用 operationId 來唯一識別一個操作，因此，**建議**遵循常見的程式設計命名慣例。
parameters	[參數物件 | 參考物件]	適用於此操作的參數列表。如果一個參數已在 路徑項目 中定義，新的定義將會覆寫它，但永遠不能移除它。此列表**必須不**包含重複的參數。一個獨特的參數是由 名稱 和 位置 的組合所定義。此列表可以使用 參考物件 來連結到在 OpenAPI 物件的 components.parameters 中定義的參數。
requestBody	請求主體物件 | 參考物件	適用於此操作的請求主體。requestBody 在 HTTP 方法中完全支援，其中 HTTP 1.1 規範 RFC7231 已明確定義了請求主體的語意。在 HTTP 規範不明確的其他情況下（例如 GET、HEAD 和 DELETE），允許使用 requestBody，但沒有明確定義的語意，如果可能，應避免使用。
responses	回應物件	從執行此操作返回的可能回應列表。
callbacks	Map[string, 回調物件 | 參考物件]	與父操作相關的可能帶外回呼的映射。鍵是回呼物件的唯一識別符。映射中的每個值都是一個 回呼物件，描述可能由 API 提供者啟動的請求和預期的回應。
deprecated	布林值	宣告此操作已棄用。消費者**應**避免使用已宣告的操作。預設值為 false。
security	[安全需求物件]	宣告可以使用哪些安全機制來執行此操作。此值列表包含可以使用的替代安全需求物件。只需滿足一個安全需求物件即可授權請求。為了使安全性成為可選項，可以在陣列中包含一個空的安全需求 ({})。此定義會覆寫任何宣告的頂層 security。要移除頂層安全宣告，可以使用空陣列。
servers	[伺服器物件]	用於服務此操作的替代 servers 陣列。如果在 路徑項目物件 或 OpenAPI 物件 層級指定了 servers 陣列，則此值將會覆寫它。

此物件可以透過規格擴充來擴充。

操作物件範例

{
  "tags": ["pet"],
  "summary": "Updates a pet in the store with form data",
  "operationId": "updatePetWithForm",
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "ID of pet that needs to be updated",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "description": "Updated name of the pet",
              "type": "string"
            },
            "status": {
              "description": "Updated status of the pet",
              "type": "string"
            }
          },
          "required": ["status"]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Pet updated.",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    },
    "405": {
      "description": "Method Not Allowed",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    }
  },
  "security": [
    {
      "petstore_auth": ["write:pets", "read:pets"]
    }
  ]
}

tags:
  - pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
  - name: petId
    in: path
    description: ID of pet that needs to be updated
    required: true
    schema:
      type: string
requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          name:
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
        required:
          - status
responses:
  '200':
    description: Pet updated.
    content:
      application/json: {}
      application/xml: {}
  '405':
    description: Method Not Allowed
    content:
      application/json: {}
      application/xml: {}
security:
  - petstore_auth:
      - write:pets
      - read:pets

外部文件物件

允許參考外部資源以取得擴充文件。

固定欄位

欄位名稱	類型	描述
description	string	目標文件的描述。可以使用 CommonMark 語法 來呈現豐富的文字格式。
url	string	**必要**。目標文件的 URI。這**必須**是 URI 形式。

此物件可以透過規格擴充來擴充。

外部文件物件範例

{
  "description": "Find more info here",
  "url": "https://example.com"
}

description: Find more info here
url: https://example.com

參數物件

描述單一操作參數。

一個獨特的參數是由 名稱 和 位置 的組合所定義。

有關百分比編碼問題的詳細檢查，包括與 application/x-www-form-urlencoded 查詢字串格式的互動，請參閱 附錄 E。

參數位置

in 欄位指定了四個可能的參數位置

• path - 與 路徑樣板 一起使用，其中參數值實際上是操作 URL 的一部分。這不包括 API 的主機或基本路徑。例如，在 /items/{itemId} 中，路徑參數是 itemId。
• query - 附加到 URL 的參數。例如，在 /items?id=### 中，查詢參數是 id。
• header - 作為請求一部分預期的自訂標頭。請注意，RFC7230 指出標頭名稱不區分大小寫。
• cookie - 用於將特定的 cookie 值傳遞給 API。

固定欄位

參數序列化的規則以兩種方式之一指定。參數物件**必須**包含 content 欄位或 schema 欄位，但不能同時包含兩者。有關將各種型別的值轉換為字串表示形式的討論，請參閱 附錄 B。

常見的固定欄位

這些欄位**可以**與 content 或 schema 一起使用。

欄位名稱	類型	描述
name	string	**必要**。參數的名稱。參數名稱是*區分大小寫的*。 如果 in 是 "path"，則 name 欄位**必須**對應於在 路徑 欄位中發生的樣板表達式，位於 路徑物件 中。有關更多資訊，請參閱 路徑樣板。 如果 in 是 "header" 且 name 欄位是 "Accept"、"Content-Type" 或 "Authorization"，則應忽略參數定義。 對於所有其他情況，name 對應於 in 欄位使用的參數名稱。
in	string	**必要**。參數的位置。可能的值為 "query"、"header"、"path" 或 "cookie"。
description	string	參數的簡短描述。這可以包含使用範例。可以使用 CommonMark 語法 來呈現豐富的文字格式。
required	布林值	確定此參數是否為必填。如果 參數位置 是 "path"，則此欄位為**必要**，且其值**必須**為 true。否則，可以包含該欄位，其預設值為 false。
deprecated	布林值	指定參數已棄用，**應**逐步停止使用。預設值為 false。
allowEmptyValue	布林值	如果為 true，客戶端**可以**傳遞零長度字串值，以代替原本會完全省略的參數，伺服器**應**將其解釋為該參數未使用。預設值為 false。如果使用 style，並且如果 行為是不適用（無法序列化），則應忽略 allowEmptyValue 的值。此欄位與參數的 結構描述物件 之間的互動是實作定義的。此欄位僅對 query 參數有效。**不建議**使用此欄位，並且可能會在以後的版本中刪除。

此物件可以透過規格擴充來擴充。

請注意，雖然如果 in 是 "header"，則 "Cookie" 作為 name 並非被禁止，但是以這種方式定義 cookie 參數的效果是未定義的；請改用 in: "cookie"。

與 schema 一起使用的固定欄位

對於更簡單的情況，可以使用 schema 和 style 來描述參數的結構和語法。當 example 或 examples 與 schema 欄位一起提供時，範例**應**與指定的結構描述匹配，並遵循參數的規定序列化策略。example 和 examples 欄位是互斥的，如果存在其中任何一個，則**應**_覆寫_結構描述中的任何 example。

**不建議**使用 schema 進行序列化，用於 in: "cookie" 參數、使用 HTTP 標頭參數（值中帶有 ; 的 name=value 對）的 in: "header" 參數，或值可能具有非 URL 安全字元的 in: "header" 參數；有關詳細資訊，請參閱 附錄 D。

欄位名稱	類型	描述
style	string	描述如何根據參數值的型別序列化參數值。預設值（基於 in 的值）：對於 "query" - "form"；對於 "path" - "simple"；對於 "header" - "simple"；對於 "cookie" - "form"。
explode	布林值	當此值為 true 時，型別為 array 或 object 的參數值會為陣列的每個值或映射的鍵值對產生單獨的參數。對於其他型別的參數，此欄位沒有任何影響。當 style 為 "form" 時，預設值為 true。對於所有其他樣式，預設值為 false。請注意，儘管 false 是 deepObject 的預設值，但 false 與 deepObject 的組合是未定義的。
allowReserved	布林值	當此值為 true 時，參數值會使用保留字元擴展進行序列化，如 RFC6570 所定義，這允許 RFC3986 的保留字元集，以及百分比編碼的三位元組保持不變，同時仍對所有其他不允許的字元（包括百分比編碼三位元組之外的 %）進行百分比編碼。應用程式仍然有責任對 查詢字串中不允許的保留字元 ([、]、#) 進行百分比編碼，或在 application/x-www-form-urlencoded 中具有特殊含義的字元 (-、&、+) 進行百分比編碼；詳情請參閱附錄 C 和 E。此欄位僅適用於 in 值為 query 的參數。預設值為 false。
schema	Schema 物件	定義用於參數的類型的 schema。
example	任意	參數潛在值的範例；請參閱使用範例。
examples	Map[ string, Example 物件 | Reference 物件]	參數潛在值的範例；請參閱使用範例。

另請參閱附錄 C：使用基於 RFC6570 的序列化，以取得更多指引。

與 content 一起使用的固定欄位

對於更複雜的情境，content 欄位可以定義參數的媒體類型和 schema，並提供其用法的範例。建議對 in: "header" 和 in: "cookie" 參數使用具有 text/plain 媒體類型的 content，其中 schema 策略不適用。

欄位名稱	類型	描述
content	Map[string, 媒體類型物件]	一個包含參數表示法的映射。鍵是媒體類型，值描述它。該映射必須僅包含一個條目。

樣式值

為了支援序列化簡單參數的常見方式，定義了一組 style 值。

style	type	in	註解
matrix	primitive、array、object	path	由 RFC6570 定義的路徑樣式參數
label	primitive、array、object	path	由 RFC6570 定義的標籤樣式參數
simple	primitive、array、object	path、header	由 RFC6570 定義的簡單樣式參數。此選項使用 OpenAPI 2.0 中的 csv 值取代 collectionFormat。
form	primitive、array、object	query、cookie	由 RFC6570 定義的表單樣式參數。此選項使用 OpenAPI 2.0 中的 csv (當 explode 為 false 時) 或 multi (當 explode 為 true 時) 值取代 collectionFormat。
spaceDelimited	array、object	query	以空格分隔的陣列值或物件屬性和值。此選項使用 OpenAPI 2.0 中等於 ssv 的 collectionFormat 取代。
pipeDelimited	array、object	query	以管道符號分隔的陣列值或物件屬性和值。此選項使用 OpenAPI 2.0 中等於 pipes 的 collectionFormat 取代。
deepObject	object	query	允許使用表單參數表示具有純量屬性的物件。未定義陣列或物件屬性的表示法。

請參閱附錄 E，以了解百分比編碼的討論，包括何時需要對分隔符號進行百分比編碼，以及處理與百分比編碼資料衝突的選項。

樣式範例

假設一個名為 color 的參數具有下列其中一個值

   string -> "blue"
   array -> ["blue", "black", "brown"]
   object -> { "R": 100, "G": 200, "B": 150 }

下表顯示了範例，如 example 或 examples 關鍵字所示，針對每個值的不同序列化。

• 值empty 表示空字串，與 allowEmptyValue 欄位無關
• 標記為n/a的組合的行為是未定義的
• undefined 欄取代了此規範先前版本中的 empty 欄，以便更好地與 RFC6570 術語保持一致，該術語將包括但不限於 null 的某些值描述為具有特殊處理的「未定義」值；值得注意的是，空字串不是未定義的
• 對於 form 和非 RFC6570 的查詢字串樣式 spaceDelimited、pipeDelimited 和 deepObject，每個範例都以 ? 作為前綴顯示，就像它是唯一的查詢參數一樣；請參閱 附錄 C，以取得有關從多個參數建構查詢字串的更多資訊，以及 附錄 D，以取得有關 form 和 cookie 參數的警告
• 請注意，? 前綴不適用於序列化 application/x-www-form-urlencoded HTTP 訊息主體，並且在該內容中使用時，必須移除或（如果手動建構字串）不添加；請參閱 Encoding 物件，以取得更多資訊
• 這些範例會根據 RFC6570 和 RFC3986 的要求進行百分比編碼；請參閱附錄 E，以深入討論百分比編碼的考量，包括為何未編碼的 | (%7C)、[ (%5B) 和 ] (%5D) 在某些環境中似乎可以運作，儘管它們不符合規範。

style	explode	undefined	string	array	object
matrix	false	;color	;color=blue	;color=blue,black,brown	;color=R,100,G,200,B,150
matrix	true	;color	;color=blue	;color=blue;color=black;color=brown	;R=100;G=200;B=150
label	false	.	.blue	.blue,black,brown	.R,100,G,200,B,150
label	true	.	.blue	.blue.black.brown	.R=100.G=200.B=150
simple	false	empty	blue	blue,black,brown	R,100,G,200,B,150
simple	true	empty	blue	blue,black,brown	R=100,G=200,B=150
form	false	?color=	?color=blue	?color=blue,black,brown	?color=R,100,G,200,B,150
form	true	?color=	?color=blue	?color=blue&color=black&color=brown	?R=100&G=200&B=150
spaceDelimited	false	不適用	不適用	?color=blue%20black%20brown	?color=R%20100%20G%20200%20B%20150
spaceDelimited	true	不適用	不適用	不適用	不適用
pipeDelimited	false	不適用	不適用	?color=blue%7Cblack%7Cbrown	?color=R%7C100%7CG%7C200%7CB%7C150
pipeDelimited	true	不適用	不適用	不適用	不適用
deepObject	false	不適用	不適用	不適用	不適用
deepObject	true	不適用	不適用	不適用	?color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150

參數物件範例

一個具有 64 位元整數陣列的標頭參數

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "integer",
      "format": "int64"
    }
  },
  "style": "simple"
}

name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple

一個字串值的路徑參數

{
  "name": "username",
  "in": "path",
  "description": "username to fetch",
  "required": true,
  "schema": {
    "type": "string"
  }
}

name: username
in: path
description: username to fetch
required: true
schema:
  type: string

一個可選的字串值查詢參數，允許透過重複查詢參數來使用多個值

{
  "name": "id",
  "in": "query",
  "description": "ID of the object to fetch",
  "required": false,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "style": "form",
  "explode": true
}

name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

一個自由格式的查詢參數，允許特定類型的未定義參數

{
  "in": "query",
  "name": "freeForm",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "integer"
    }
  },
  "style": "form"
}

in: query
name: freeForm
schema:
  type: object
  additionalProperties:
    type: integer
style: form

一個使用 content 定義序列化的複雜參數

{
  "in": "query",
  "name": "coordinates",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": ["lat", "long"],
        "properties": {
          "lat": {
            "type": "number"
          },
          "long": {
            "type": "number"
          }
        }
      }
    }
  }
}

in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number

請求主體物件

描述單個請求主體。

固定欄位

欄位名稱	類型	描述
description	string	請求主體的簡短描述。這可以包含使用範例。可以使用 CommonMark 語法來表示豐富的文字。
content	Map[string, 媒體類型物件]	必要。請求主體的內容。鍵是媒體類型或 媒體類型範圍，值描述它。對於符合多個鍵的請求，僅適用最特定的鍵。例如，"text/plain" 會覆寫 "text/*"
required	布林值	確定請求中是否需要請求主體。預設值為 false。

此物件可以透過規格擴充來擴充。

請求主體範例

一個具有參考 schema 定義的請求主體。

{
  "description": "user to add to the system",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
        "user": {
          "summary": "User Example",
          "externalValue": "https://foo.bar/examples/user-example.json"
        }
      }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
        "user": {
          "summary": "User example in XML",
          "externalValue": "https://foo.bar/examples/user-example.xml"
        }
      }
    },
    "text/plain": {
      "examples": {
        "user": {
          "summary": "User example in Plain text",
          "externalValue": "https://foo.bar/examples/user-example.txt"
        }
      }
    },
    "*/*": {
      "examples": {
        "user": {
          "summary": "User example in other format",
          "externalValue": "https://foo.bar/examples/user-example.whatever"
        }
      }
    }
  }
}

description: user to add to the system
content:
  application/json:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example
        externalValue: https://foo.bar/examples/user-example.json
  application/xml:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example in XML
        externalValue: https://foo.bar/examples/user-example.xml
  text/plain:
    examples:
      user:
        summary: User example in plain text
        externalValue: https://foo.bar/examples/user-example.txt
  '*/*':
    examples:
      user:
        summary: User example in other format
        externalValue: https://foo.bar/examples/user-example.whatever

媒體類型物件

每個媒體類型物件都提供由其鍵識別的媒體類型的 schema 和範例。

當提供 example 或 examples 時，範例應符合指定的 schema，並採用媒體類型及其編碼指定的正確格式。example 和 examples 欄位是互斥的，如果存在其中任何一個，則應覆寫 schema 中的任何 example。請參閱 使用範例，以取得有關指定範例的不同方式的進一步指引，包括非 JSON/YAML 值。

固定欄位

欄位名稱	類型	描述
schema	Schema 物件	定義請求、回應、參數或標頭內容的 schema。
example	任意	媒體類型的範例；請參閱使用範例。
examples	Map[ string, Example 物件 | Reference 物件]	媒體類型的範例；請參閱使用範例。
encoding	Map[string, Encoding 物件]	屬性名稱及其編碼資訊之間的映射。作為屬性名稱的鍵，必須以屬性的形式存在於 schema 中。encoding 欄位應僅適用於 請求主體物件，且僅當媒體類型為 multipart 或 application/x-www-form-urlencoded 時才適用。如果未為屬性提供 Encoding 物件，則行為由 Encoding 物件記錄的預設值決定。

此物件可以透過規格擴充來擴充。

媒體類型範例

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat": {
        "summary": "An example of a cat",
        "value": {
          "name": "Fluffy",
          "petType": "Cat",
          "color": "White",
          "gender": "male",
          "breed": "Persian"
        }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value": {
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        }
      },
      "frog": {
        "$ref": "#/components/examples/frog-example"
      }
    }
  }
}

application/json:
  schema:
    $ref: '#/components/schemas/Pet'
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: '#/components/examples/frog-example'

檔案上傳的注意事項

與 OpenAPI 2.0 相反，OAS 3.x 中的 file 輸入/輸出內容與任何其他 schema 類型使用相同的語意進行描述。

與 OAS 3.0 相反，format 關鍵字對 OAS 3.1 中 schema 的內容編碼沒有影響。而是使用 JSON Schema 的 contentEncoding 和 contentMediaType 關鍵字。請參閱使用二進位資料，以了解如何使用這些關鍵字建立各種情境的模型，以及如何從先前的 format 用法進行遷移。

範例

以二進位 (octet-stream) 傳輸的內容可以省略 schema

# a PNG image as a binary file:
content:
  image/png: {}

# an arbitrary binary file:
content:
  application/octet-stream: {}

# arbitrary JSON without constraints beyond being syntactically valid:
content:
  application/json: {}

這些範例適用於檔案上傳的輸入酬載或回應酬載。

用於在 POST 作業中提交檔案的 requestBody 可能如下列範例所示

requestBody:
  content:
    application/octet-stream: {}

此外，可以指定特定的媒體類型

# multiple, specific media types may be specified:
requestBody:
  content:
    # a binary file of type png or jpeg
    image/jpeg: {}
    image/png: {}

若要上傳多個檔案，必須使用 multipart 媒體類型，如 範例：具有多個檔案的多部分表單所示。

支援 x-www-form-urlencoded 請求主體

請參閱編碼 x-www-form-urlencoded 媒體類型，以取得指引和範例，無論是否使用 encoding 欄位。

multipart 內容的特殊注意事項

請參閱編碼 multipart 媒體類型，以取得進一步的指引和範例，無論是否使用 encoding 欄位。

Encoding 物件

應用於單個 schema 屬性的單個編碼定義。請參閱附錄 B，以取得有關將各種類型的值轉換為字串表示法的討論。

使用 Content-Disposition: form-data 的 name 參數將屬性與 multipart 部分相關聯，並使用查詢字串參數名稱將屬性與 application/x-www-form-urlencoded 相關聯。在這兩種情況下，它們的順序都是實作定義的。

關於表單媒體類型的百分比編碼詳細探討，請參閱附錄 E。

固定欄位

常見的固定欄位

這些欄位可以搭配或不搭配下一節定義的 RFC6570 風格序列化欄位一起使用。

欄位名稱	類型	描述
contentType	string	用於編碼特定屬性的 Content-Type。其值是一個以逗號分隔的列表，每個元素可以是特定的媒體類型 (例如 image/png) 或萬用字元媒體類型 (例如 image/*)。預設值取決於屬性類型，如下表所示。
headers	Map[string, 標頭物件 | 參考物件]	一個允許提供額外資訊作為標頭的映射。Content-Type 會單獨描述，並且在此節中應被忽略。如果請求主體媒體類型不是 multipart，則應忽略此欄位。

此物件可以透過規格擴充來擴充。

contentType 的預設值如下，其中 contentEncoding 欄中的 n/a 表示 contentEncoding 的存在與否或值無關

type	contentEncoding	預設 contentType
不存在	不適用	application/octet-stream
string	存在	application/octet-stream
string	不存在	text/plain
number、integer 或 boolean	不適用	text/plain
object	不適用	application/json
array	不適用	根據 items 綱要的 type

如何處理 type 值為 null 取決於如何序列化 null 值。如果完全省略 null 值，則 contentType 無關緊要。關於資料類型轉換選項的討論，請參閱附錄 B。

RFC6570 風格序列化的固定欄位

欄位名稱	類型	描述
style	string	描述特定屬性值將如何根據其類型進行序列化。關於 style 欄位的詳細資訊，請參閱參數物件。其行為遵循與 query 參數相同的值，包括預設值。請注意，查詢字串中使用的初始 ? 不用於 application/x-www-form-urlencoded 訊息主體中，且必須移除 (如果使用 RFC6570 實作) 或直接不新增 (如果手動建構字串)。如果請求主體媒體類型不是 application/x-www-form-urlencoded 或 multipart/form-data，則應忽略此欄位。如果明確定義了值，則應忽略 contentType 的值 (隱含或明確)。
explode	布林值	當此值為 true 時，類型為 array 或 object 的屬性值會為陣列的每個值或映射的鍵值對產生單獨的參數。對於其他類型的屬性，此欄位無效。當 style 為 "form" 時，預設值為 true。對於所有其他樣式，預設值為 false。請注意，儘管 false 是 deepObject 的預設值，但 false 與 deepObject 的組合未定義。如果請求主體媒體類型不是 application/x-www-form-urlencoded 或 multipart/form-data，則應忽略此欄位。如果明確定義了值，則應忽略 contentType 的值 (隱含或明確)。
allowReserved	布林值	當此值為 true 時，參數值會使用保留擴展進行序列化，如 RFC6570 所定義，這允許 RFC3986 的保留字元集以及百分比編碼的三元組保持不變，同時仍會百分比編碼所有其他不允許的字元 (包括百分比編碼三元組之外的 %)。應用程式仍負責百分比編碼 不允許在查詢字串中 ([、]、#) 或在 application/x-www-form-urlencoded 中具有特殊含義 (-、&、+) 的保留字元；詳細資訊請參閱附錄 C 和 E。預設值為 false。如果請求主體媒體類型不是 application/x-www-form-urlencoded 或 multipart/form-data，則應忽略此欄位。如果明確定義了值，則應忽略 contentType 的值 (隱含或明確)。

另請參閱附錄 C：使用 RFC6570 實作，以取得其他指南，包括因 RFC6570 的百分比編碼規則與 multipart/form-data 媒體類型之間的互動所造成的困難。

請注意，至少存在一個具有明確值的 style、explode 或 allowReserved 等同於使用 schema 與 in: "query" 參數物件。缺少所有這三個欄位等同於使用 content，但媒體類型是在 contentType 中指定，而不是透過媒體類型物件指定。

編碼 x-www-form-urlencoded 媒體類型

若要透過 RFC1866 使用表單 URL 編碼提交內容，請在 請求主體物件下的 媒體類型物件中使用 application/x-www-form-urlencoded 媒體類型。此組態表示當傳遞給伺服器時，請求主體必須根據 RFC1866 進行編碼，在將任何複雜物件序列化為字串表示形式之後。

關於表單媒體類型的百分比編碼詳細探討，請參閱附錄 E。

範例：具有 JSON 值的 URL 編碼表單

當沒有 encoding 欄位時，序列化策略基於編碼物件的預設值

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # complex types are stringified to support RFC 1866
            type: object
            properties: {}

在此範例中，請考慮一個 id 為 f81d4fae-7dec-11d0-a765-00a0c91e6bf6 和一個美國樣式的地址 (帶有 ZIP+4)，如下所示

{
  "streetAddress": "123 Example Dr.",
  "city": "Somewhere",
  "state": "CA",
  "zip": "99999+1234"
}

假設 JSON 值最精簡的表示形式 (已移除不必要的空白)，我們預期會看到以下請求主體，其中空格字元已取代為 +，並且 +、"、{ 和 } 已分別進行百分比編碼為 %2B、%22、%7B 和 %7D

id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6&address=%7B%22streetAddress%22:%22123+Example+Dr.%22,%22city%22:%22Somewhere%22,%22state%22:%22CA%22,%22zip%22:%2299999%2B1234%22%7D

請注意，id 關鍵字會根據編碼物件的預設行為視為 text/plain，並按原樣序列化。如果將其視為 application/json，則序列化的值將是包含引號的 JSON 字串，該字串將進行百分比編碼為 %22。

以下是 id 參數 (不含 address) 序列化為 application/json 而非 text/plain，然後根據 RFC1866 進行編碼

id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22

範例：具有二進位值的 URL 編碼表單

請注意，application/x-www-form-urlencoded 是一種文字格式，需要對任何二進位資料進行 base64 編碼

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          name:
            type: string
          icon:
            # The default with "contentEncoding" is application/octet-stream,
            # so we need to set image media type(s) in the Encoding Object.
            type: string
            contentEncoding: base64url
  encoding:
    icon:
      contentType: image/png, image/jpeg

給定名稱為 example 和一個實心紅色 2x2 像素 PNG 的 icon，這將產生一個請求主體，其內容為

name=example&icon=iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC_xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAAqADAAQAAAABAAAAAgAAAADO0J6QAAAAEElEQVQIHWP8zwACTGCSAQANHQEDqtPptQAAAABJRU5ErkJggg%3D%3D

請注意，結尾的 = 填充字元需要進行百分比編碼，即使使用「URL 安全」的 contentEncoding: base64url。根據 RFC4648，某些 base64 解碼實作可能能夠在不使用填充的情況下使用字串。但是，這不能保證，因此保留填充並依賴百分比解碼可能會更具互操作性。

編碼 multipart 媒體類型

在傳輸表單作為請求主體時，通常會使用 multipart/form-data 作為 Content-Type。與 OpenAPI 2.0 相反，當使用 multipart 內容時，必須使用 schema 來定義操作的輸入參數。這支援複雜的結構以及多個檔案上傳的支援機制。

form-data 配置及其 name 參數對於 multipart/form-data 是強制性的 (RFC7578)。陣列屬性會透過將相同的 name 應用於多個部分來處理，這是 RFC7578 建議的，用於每個表單欄位提供多個值。有關非 ASCII 部分名稱的指南，請參閱 RFC7578。

各種其他 multipart 類型，最著名的是 multipart/mixed (RFC2046) 既不要求也不禁止特定的 Content-Disposition 值，這表示必須小心確保所有相關軟體都支援任何使用的值。目前無法將綱要屬性與媒體類型 (例如 multipart/mixed) 中未命名的有序部分關聯，但當 Content-Disposition: form-data 與 name 參數一起使用時，實作可能會選擇支援此類類型。

請注意，一般來說，multipart 媒體類型 (RFC2046) 和尤其是 multi-part/form-data (RFC7578) 對可使用的標頭有重大限制。

另請注意，對於 multipart/form-data (RFC7578) 已棄用 Content-Transfer-Encoding，因為 HTTP 中支援二進位資料。

+為多部分欄位使用 contentEncoding 等同於指定一個編碼物件，該物件的 headers 欄位包含 Content-Transfer-Encoding，並且綱要要求使用 contentEncoding 中使用的值。 +如果 contentEncoding 用於具有編碼物件的多部分欄位，該物件的 headers 欄位包含 Content-Transfer-Encoding，並且綱要不允許使用 contentEncoding 的值，則序列化和剖析的結果未定義。

請注意，如使用二進位資料中所述，如果編碼物件的 contentType (無論是明確設定還是透過其預設值規則隱含設定) 與綱要物件中的 contentMediaType 不一致，則應忽略 contentMediaType。正因如此，且由於編碼物件的 contentType 預設規則未將綱要物件的 contentMediaType 納入考量，因此不建議將 contentMediaType 與編碼物件一起使用。

關於表單媒體類型的百分比編碼詳細探討，請參閱附錄 E。

範例：基本多部分表單

當未使用 encoding 欄位時，編碼由編碼物件的預設值決定

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            # default for primitives without a special format is text/plain
            type: string
            format: uuid
          profileImage:
            # default for string with binary format is `application/octet-stream`
            type: string
            format: binary
          addresses:
            # default for arrays is based on the type in the `items`
            # subschema, which is an object, so `application/json`
            type: array
            items:
              $ref: '#/components/schemas/Address'

範例：具有編碼物件的多部分表單

使用 encoding，我們可以為二進位資料設定更具體的類型，或為複雜值設定非 JSON 格式。我們還可以描述每個部分的標頭

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            # default is `text/plain`
            type: string
            format: uuid
          addresses:
            # default based on the `items` subschema would be
            # `application/json`, but we want these address objects
            # serialized as `application/xml` instead
            description: addresses in XML format
            type: array
            items:
              $ref: '#/components/schemas/Address'
          profileImage:
            # default is application/octet-stream, but we can declare
            # a more specific image type or types
            type: string
            format: binary
      encoding:
        addresses:
          # require XML Content-Type in utf-8 encoding
          # This is applied to each address part corresponding
          # to each address in he array
          contentType: application/xml; charset=utf-8
        profileImage:
          # only accept png or jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

範例：具有多個檔案的多部分表單

根據 RFC7578，單個表單欄位的多個檔案會使用每個檔案部分相同的名稱 (在此範例中為 file) 來上傳

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items: {}

如編碼物件的 contentType 欄位文件所述，items 的空結構描述表示媒體類型為 application/octet-stream。

回應物件

操作預期回應的容器。此容器將 HTTP 回應碼對應到預期的回應。

此文件不一定會涵蓋所有可能的 HTTP 回應碼，因為這些回應碼可能無法預先得知。但是，此文件應涵蓋成功的操作回應以及任何已知的錯誤。

default 可以用作 Responses 物件中未個別涵蓋的所有 HTTP 碼的預設回應物件。

Responses 物件必須包含至少一個回應碼，如果只提供一個回應碼，則應為成功操作呼叫的回應。

固定欄位

欄位名稱	類型	描述
default	回應物件 | 參考物件	針對特定 HTTP 回應碼宣告以外的回應文件。使用此欄位來涵蓋未宣告的回應。

模式化欄位

欄位模式	類型	描述
HTTP 狀態碼	回應物件 | 參考物件	任何HTTP 狀態碼都可以用作屬性名稱，但每個代碼只能有一個屬性，以描述該 HTTP 狀態碼的預期回應。為了 JSON 和 YAML 之間的相容性，此欄位必須用引號括起來（例如，「200」）。若要定義回應碼的範圍，此欄位可以包含大寫的萬用字元 X。例如，2XX 代表 200 和 299 之間的所有回應碼。僅允許以下範圍定義：1XX、2XX、3XX、4XX 和 5XX。如果使用明確的代碼定義回應，則明確的代碼定義優先於該代碼的範圍定義。

此物件可以透過規格擴充來擴充。

Responses 物件範例

針對成功操作的 200 回應，以及其他回應的預設回應（表示錯誤）

{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}

'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'

回應物件

描述 API 操作的單一回應，包括設計時、基於回應的靜態 links 到操作。

固定欄位

欄位名稱	類型	描述
description	string	必要。回應的描述。可使用CommonMark 語法進行豐富文字表示。
headers	Map[string, 標頭物件 | 參考物件]	將標頭名稱對應到其定義。RFC7230 指出標頭名稱不區分大小寫。如果使用名稱 "Content-Type" 定義回應標頭，則應忽略該標頭。
content	Map[string, 媒體類型物件]	包含潛在回應酬載描述的對應。索引鍵是媒體類型或媒體類型範圍，而值則描述它。對於符合多個索引鍵的回應，僅適用最特定的索引鍵。例如，"text/plain" 會覆寫 "text/*"
links	Map[string, 連結物件 | 參考物件]	可以從回應中追蹤的操作連結對應。對應的索引鍵是連結的簡短名稱，遵循元件物件名稱的命名限制。

此物件可以透過規格擴充來擴充。

回應物件範例

複雜類型陣列的回應

{
  "description": "A complex object array response",
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/VeryComplexType"
        }
      }
    }
  }
}

description: A complex object array response
content:
  application/json:
    schema:
      type: array
      items:
        $ref: '#/components/schemas/VeryComplexType'

字串類型回應

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  }
}

description: A simple string response
content:
  text/plain:
    schema:
      type: string

具有標頭的純文字回應

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      },
      "example": "whoa!"
    }
  },
  "headers": {
    "X-Rate-Limit-Limit": {
      "description": "The number of allowed requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Remaining": {
      "description": "The number of remaining requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Reset": {
      "description": "The number of seconds left in the current period",
      "schema": {
        "type": "integer"
      }
    }
  }
}

description: A simple string response
content:
  text/plain:
    schema:
      type: string
    example: 'whoa!'
headers:
  X-Rate-Limit-Limit:
    description: The number of allowed requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    schema:
      type: integer

沒有傳回值的回應

{
  "description": "object created"
}

description: object created

回呼物件

與父操作相關的可能頻外回呼對應。對應中的每個值都是路徑項目物件，用於描述 API 提供者可能起始的一組請求和預期的回應。用於識別路徑項目物件的索引鍵值是一個表達式，在執行階段評估，以識別用於回呼操作的 URL。

若要描述來自 API 提供者的輸入請求，而與另一個 API 呼叫無關，請使用 webhooks 欄位。

模式化欄位

欄位模式	類型	描述
{expression}	路徑項目物件	用於定義回呼請求和預期回應的路徑項目物件。有一個完整範例可用。

此物件可以透過規格擴充來擴充。

索引鍵表達式

識別路徑項目物件的索引鍵是一個執行階段表達式，可以在執行階段 HTTP 請求/回應的內容中評估，以識別用於回呼請求的 URL。一個簡單的範例可能是 $request.body#/url。但是，使用執行階段表達式可以存取完整的 HTTP 訊息。這包括存取 JSON 指標 RFC6901 可以參考的任何主體部分。

例如，假設有以下 HTTP 請求

POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 188

{
  "failedUrl": "https://clientdomain.com/failed",
  "successUrls": [
    "https://clientdomain.com/fast",
    "https://clientdomain.com/medium",
    "https://clientdomain.com/slow"
  ]
}

導致

201 Created
Location: https://example.org/subscription/1

以下範例顯示各種表達式如何評估，假設回呼操作具有名為 eventType 的路徑參數和名為 queryUrl 的查詢參數。

表達式	值
$url	https://example.org/subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning
$method	POST
$request.path.eventType	myevent
$request.query.queryUrl	https://clientdomain.com/stillrunning
$request.header.content-type	application/json
$request.body#/failedUrl	https://clientdomain.com/failed
$request.body#/successUrls/1	https://clientdomain.com/medium
$response.header.Location	https://example.org/subscription/1

回呼物件範例

以下範例使用使用者提供的 queryUrl 查詢字串參數來定義回呼 URL。這類似於webhook，但不同之處在於回呼僅由於傳送 queryUrl 的初始請求而發生。

myCallback:
  '{$request.query.queryUrl}':
    post:
      requestBody:
        description: Callback payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

以下範例顯示回呼，其中伺服器是硬式編碼的，但查詢字串參數是從請求主體中的 id 和 email 屬性填入。

transactionCallback:
  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
    post:
      requestBody:
        description: Callback payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

範例物件

將內部或外部範例值與基本 summary 和 description 中繼資料分組的物件。此物件通常用於名為 examples (複數) 的欄位，並且是舊版 example (單數) 欄位的可參考替代方案，這些欄位不支援參考或中繼資料。

範例允許示範 OpenAPI 中屬性、參數和物件的用法。

固定欄位

欄位名稱	類型	描述
summary	string	範例的簡短描述。
description	string	範例的詳細描述。可使用CommonMark 語法進行豐富文字表示。
value	任意	內嵌的常值範例。value 欄位和 externalValue 欄位是互斥的。若要表示無法以 JSON 或 YAML 自然表示的媒體類型的範例，請使用字串值來包含範例，並在必要時逸出。
externalValue	string	識別常值範例的 URI。這提供了參考無法輕易包含在 JSON 或 YAML 文件中的範例的功能。value 欄位和 externalValue 欄位是互斥的。請參閱解析相對參考的規則。

此物件可以透過規格擴充來擴充。

在所有情況下，範例值應與其相關聯值的結構描述相容。工具實作可能會選擇自動驗證相容性，如果範例值不相容，則拒絕該範例值。

使用範例

範例物件可用於參數物件和媒體類型物件。在這兩個物件中，都是透過 examples (複數) 欄位來完成。但是，還有幾種其他方式可以提供範例：與這兩個物件中的 examples 互斥的 example (單數) 欄位，以及結構描述物件中出現的兩個關鍵字（已淘汰的單數 example 和目前的複數 examples，它採用範例陣列），其出現在這兩個物件的 schema 欄位中。這些欄位的每一個都具有略微不同的考量。

結構描述物件的欄位用於顯示範例值，而不考慮它們如何格式化為參數或媒體類型表示法。examples 陣列是 JSON 結構描述的一部分，並且是在結構描述物件中包含範例的慣用方式，而保留 example 完全是為了與舊版 OpenAPI 規格相容。

參數或媒體類型物件中的互斥欄位用於顯示範例值，這些範例值都應該符合結構描述，並且應格式化為它們在序列化參數中或在媒體類型表示法中出現的方式。確切的序列化和編碼是由參數物件中的各種欄位或媒體類型物件的編碼物件中決定的。因為使用這些欄位的範例代表資料的最終序列化形式，所以它們應覆寫相應結構描述物件中的任何 example。

參數或媒體類型物件中的單數 example 欄位對於簡單範例來說簡潔方便，但使用 examples 下的範例物件並未提供任何其他優勢。

有些範例無法直接以 JSON 或 YAML 表示。對於提供範例的所有三種方式，這些範例可以顯示為字串值，並使用任何必要的逸出來使字串在構成 OpenAPI 描述的文件 JSON 或 YAML 格式中有效。使用範例物件，此類值可以透過 externalValue 欄位來處理。

範例物件範例

在請求主體中

requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value:
            foo: bar
        bar:
          summary: A bar example
          value:
            bar: baz
    application/xml:
      examples:
        xmlExample:
          summary: This is an example in XML
          externalValue: https://example.org/examples/address-example.xml
    text/plain:
      examples:
        textExample:
          summary: This is a text example
          externalValue: https://foo.bar/examples/address-example.txt

在參數中

parameters:
  - name: zipCode
    in: query
    schema:
      type: string
      format: zip-code
    examples:
      zip-example:
        $ref: '#/components/examples/zip-example'

在回應中

responses:
  '200':
    description: your car appointment has been booked
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SuccessResponse'
        examples:
          confirmation-success:
            $ref: '#/components/examples/confirmation-success'

JSON 字串的兩種不同用法

首先，一個只是 JSON 字串（而不是包含字串的物件）的請求或回應主體

"application/json": {
  "schema": {
    "type": "string"
  },
  "examples": {
    "jsonBody": {
      "description": "A body of just the JSON string \"json\"",
      "value": "json"
    }
  }
}

application/json:
  schema:
    type: string
  examples:
    jsonBody:
      description: 'A body of just the JSON string "json"'
      value: json

在以上範例中，我們可以只按原樣顯示 JSON 字串（或任何 JSON 值），而不是將序列化的 JSON 值填入 JSON 字串，那樣看起來會像是 "\"json\""。

相反地，一個 URL 樣式表單主體內編碼的 JSON 字串

"application/x-www-form-urlencoded": {
  "schema": {
    "type": "object",
    "properties": {
      "jsonValue": {
        "type": "string"
      }
    }
  },
  "encoding": {
    "jsonValue": {
      "contentType": "application/json"
    }
  },
  "examples": {
    "jsonFormValue": {
      "description": "The JSON string \"json\" as a form value",
      "value": "jsonValue=%22json%22"
    }
  }
}

application/x-www-form-urlencoded:
  schema:
    type: object
    properties:
      jsonValue:
        type: string
  encoding:
    jsonValue:
      contentType: application/json
  examples:
    jsonFormValue:
      description: 'The JSON string "json" as a form value'
      value: jsonValue=%22json%22

在此範例中，JSON 字串必須在將其編碼到 URL 表單值之前進行序列化，因此範例包含作為 JSON 序列化一部分的引號，然後對其進行 URL 百分比編碼。

連結物件

連結物件代表回應的可能設計時連結。連結的存在不保證呼叫者能夠成功叫用它，而是提供回應和其他操作之間已知的關係和周遊機制。

與動態連結（即在回應酬載中提供的連結）不同，OAS 連結機制不需要執行階段回應中的連結資訊。

若要計算連結並提供執行連結的指示，執行階段表達式用於存取操作中的值，並在叫用連結操作時將其用作參數。

固定欄位

欄位名稱	類型	描述
operationRef	string	OAS 操作的 URI 參考。此欄位與 operationId 欄位互斥，並且必須指向操作物件。相對 operationRef 值可以用來尋找 OpenAPI 描述中現有的操作物件。
operationId	string	由唯一 operationId 定義的現有、可解析的 OAS 操作的名稱。此欄位與 operationRef 欄位互斥。
parameters	對應 [字串、任何 | {expression}]	表示要傳遞至使用 operationId 指定或透過 operationRef 識別的操作的參數的對應。索引鍵是要使用的參數名稱（可選擇使用參數位置限定，例如，路徑中 id 參數的 path.id），而值可以是常數或要評估並傳遞至連結操作的表達式。
requestBody	任何 | {expression}	常值或{expression}，在呼叫目標操作時用作請求主體。
description	string	連結的描述。可使用CommonMark 語法進行豐富文字表示。
server	伺服器物件	目標操作要使用的伺服器物件。

此物件可以透過規格擴充來擴充。

一個連結的操作必須使用 operationRef 或 operationId 來識別。被識別或參考的操作必須是唯一的，且在 operationId 的情況下，它必須在 OpenAPI 描述（OAD）的範圍內解析。由於名稱衝突的可能性，對於多文件 OAD，建議使用 operationRef 語法。然而，由於操作的使用取決於 Paths Object 中的 URL 路徑範本，因此來自任何在 OAD 中被多次參考的 Path Item Object 的操作都無法明確解析。在這種不明確的情況下，產生的行為是實現定義的，並且可能會導致錯誤。

請注意，不可能為 parameters 提供一個與運行時表達式語法相符的常數值。有可能出現不明確的參數名稱，例如 name: "id", in: "path" 和 name: "path.id", in: "query"；不建議這樣做，且行為是實現定義的，但是實作應該偏好合格的解釋（path.id 作為路徑參數），因為名稱始終可以限定以消除歧義（例如，對查詢參數使用 query.path.id）。

範例

計算一個請求操作的連結，其中 $request.path.id 用於將請求參數傳遞到連結的操作。

paths:
  /users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: the user identifier, as userId
        schema:
          type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userid: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
      - name: userid
        in: path
        required: true
        description: the user identifier, as userId
        schema:
          type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address

當運行時表達式無法評估時，沒有參數值傳遞到目標操作。

可以從響應主體中使用值來驅動連結的操作。

links:
  address:
    operationId: getUserAddressByUUID
    parameters:
      # get the `uuid` field from the `uuid` field in the response body
      userUuid: $response.body#/uuid

客戶端可以自行決定是否遵循所有連結。僅憑關係的存在，並不能保證客戶端有權限或有能力成功呼叫該連結。

operationRef 範例

由於對 operationId 的參考可能不可行（operationId 是 Operation Object 中的可選欄位），因此也可以通過相對的 operationRef 進行參考

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1%7Busername%7D/get'
    parameters:
      username: $response.body#/username

或是 URI operationRef

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1%7Busername%7D/get
    parameters:
      username: $response.body#/username

請注意，在使用 operationRef 時，當使用 JSON 指針時，必須使用轉義的斜線，並且當使用 JSON 指針作為 URI 片段時，必須將 { 和 } 分別 URL 編碼為 %7B 和 %7D。

運行時表達式

運行時表達式允許根據僅在實際 API 呼叫中的 HTTP 消息中可用的資訊來定義值。此機制由 Link Objects 和 Callback Objects 使用。

運行時表達式由以下 ABNF 語法定義

    expression = "$url" / "$method" / "$statusCode" / "$request." source / "$response." source
    source     = header-reference / query-reference / path-reference / body-reference
    header-reference = "header." token
    query-reference  = "query." name
    path-reference   = "path." name
    body-reference   = "body" ["#" json-pointer ]
    json-pointer    = *( "/" reference-token )
    reference-token = *( unescaped / escaped )
    unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
                    ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
    escaped         = "~" ( "0" / "1" )
                    ; representing '~' and '/', respectively
    name = *( CHAR )
    token = 1*tchar
    tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "."
          / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA

在此，json-pointer 取自 RFC6901，char 取自 RFC7159，而 token 取自 RFC7230。

name 識別符號區分大小寫，而 token 不區分大小寫。

下表提供了運行時表達式的範例以及它們在值中的使用範例

範例

來源位置	範例表達式	註解
HTTP 方法	$method	$method 的允許值將是 HTTP 操作的值。
請求的媒體類型	$request.header.accept
請求參數	$request.path.id	請求參數必須在父操作的 parameters 區段中宣告，否則無法評估。這包括請求標頭。
請求主體屬性	$request.body#/user/uuid	在接受有效負載的操作中，可以參考 requestBody 的一部分或整個主體。
請求 URL	$url
響應值	$response.body#/status	在返回有效負載的操作中，可以參考響應主體的一部分或整個主體。
響應標頭	$response.header.Server	僅提供單個標頭值

運行時表達式保留被參考值的類型。表達式可以通過用 {} 大括號包圍表達式來嵌入到字符串值中。

標頭物件

描述 HTTP 響應和 multipart 表示中的各個部分的單個標頭；有關哪些標頭可以被描述的限制，請參閱相關的 Response Object 和 Encoding Object 文件。

Header Object 遵循 Parameter Object 的結構，包括根據是否存在 schema 或 content 來確定其序列化策略，但有以下更改

1. name 不能指定，它在相應的 headers 映射中給出。
2. in 不能指定，它隱式地在 header 中。
3. 所有受位置影響的特性都必須適用於 header 的位置（例如，style）。這表示 allowEmptyValue 和 allowReserved 不能使用，且 style（如果使用）必須限制為 "simple"。

固定欄位

常見的固定欄位

這些欄位**可以**與 content 或 schema 一起使用。

欄位名稱	類型	描述
description	string	標頭的簡短描述。這可能包含使用範例。CommonMark 語法可用於豐富文字表示。
required	布林值	確定此標頭是否為強制性的。預設值為 false。
deprecated	布林值	指定標頭已棄用，應停止使用。預設值為 false。

此物件可以透過規格擴充來擴充。

與 schema 一起使用的固定欄位

對於較簡單的場景，schema 和 style 可以描述標頭的結構和語法。當 example 或 examples 與 schema 欄位一起提供時，範例必須遵循標頭的規定序列化策略。

對於值中帶有參數（名稱=值對，後跟 ;）或值可能具有非 URL 安全字元的標頭，不建議使用 schema 進行序列化；請參閱 附錄 D 以了解詳細資訊。

當 example 或 examples 與 schema 欄位一起提供時，範例應與指定的 schema 相符，並遵循標頭的規定序列化策略。example 和 examples 欄位是互斥的，如果存在任何一個，則應覆蓋 schema 中的任何 example。

欄位名稱	類型	描述
style	string	描述標頭值將如何序列化。預設值（且標頭的唯一合法值）為 "simple"。
explode	布林值	當此值為 true 時，類型為 array 或 object 的標頭值會生成一個單一標頭，其值為陣列項目或映射的鍵值對的逗號分隔列表，請參閱 Style Examples。對於其他資料類型，此欄位沒有任何作用。預設值為 false。
schema	Schema Object | Reference Object	定義標頭所用類型的 schema。
example	任意	標頭的潛在值範例；請參閱 Working With Examples。
examples	Map[ string, Example 物件 | Reference 物件]	標頭的潛在值範例；請參閱 Working With Examples。

另請參閱附錄 C：使用基於 RFC6570 的序列化，以取得更多指引。

與 content 一起使用的固定欄位

對於更複雜的場景，content 欄位可以定義標頭的媒體類型和 schema，並提供其使用範例。對於 schema 策略不適用的標頭，建議使用 content 與 text/plain 媒體類型。

欄位名稱	類型	描述
content	Map[string, 媒體類型物件]	包含標頭表示的映射。鍵是媒體類型，值描述它。映射必須只包含一個條目。

Header Object 範例

類型為 integer 的簡單標頭

"X-Rate-Limit-Limit": {
  "description": "The number of allowed requests in the current period",
  "schema": {
    "type": "integer"
  }
}

X-Rate-Limit-Limit:
  description: The number of allowed requests in the current period
  schema:
    type: integer

要求存在一個強 ETag 標頭（其值以 " 而不是 W/ 開頭）。請注意 content 的使用，因為使用 schema 和 style 將需要將 " 百分比編碼為 %22

"ETag": {
  "required": true,
  "content": {
    "text/plain": {
      "schema": {
        "type": "string",
        "pattern": "^\""
      }
    }
  }
}

ETag:
  required: true
  content:
    text/plain:
      schema:
        type: string
        pattern: ^"

Tag Object

將元數據添加到 Operation Object 使用的單個標籤。對於在 Operation Object 實例中定義的每個標籤，並非必須都有一個 Tag Object。

固定欄位

欄位名稱	類型	描述
name	string	必要。標籤的名稱。
description	string	標籤的描述。CommonMark 語法可用於豐富文字表示。
externalDocs	外部文件物件	此標籤的其他外部文件。

此物件可以透過規格擴充來擴充。

Tag Object 範例

{
  "name": "pet",
  "description": "Pets operations"
}

name: pet
description: Pets operations

Reference Object

一個簡單的物件，允許參考 OpenAPI 描述中的其他組件，無論是內部還是外部。

$ref 字符串值包含一個 URI RFC3986，它標識被參考的值。

請參閱解析 相對參考的規則。

固定欄位

欄位名稱	類型	描述
$ref	string	必要。參考識別符號。這必須採用 URI 的形式。
summary	string	一個簡短的摘要，預設情況下應覆蓋被參考組件的摘要。如果被參考的物件類型不允許 summary 欄位，則此欄位無效。
description	string	預設情況下應覆蓋被參考組件的描述。 CommonMark 語法可用於豐富文字表示。如果被參考的物件類型不允許 description 欄位，則此欄位無效。

此物件不能使用其他屬性進行擴充，任何添加的屬性都應被忽略。

請注意，對其他屬性的這種限制是 Reference Objects 和包含 $ref 關鍵字的 Schema Objects 之間的一個區別。

Reference Object 範例

{
  "$ref": "#/components/schemas/Pet"
}

$ref: '#/components/schemas/Pet'

相對 Schema 文件範例

{
  "$ref": "Pet.json"
}

$ref: Pet.yaml

具有嵌入式 Schema 的相對文件範例

{
  "$ref": "definitions.json#/Pet"
}

$ref: definitions.yaml#/Pet

Schema 物件

Schema Object 允許定義輸入和輸出資料類型。這些類型可以是物件，也可以是基本類型和陣列。此物件是 JSON Schema Specification Draft 2020-12 的超集。空 schema（允許驗證任何實例）可以用布林值 true 表示，而允許不驗證任何實例的 schema 可以用布林值 false 表示。

有關關鍵字的更多資訊，請參閱 JSON Schema Core 和 JSON Schema Validation。

除非另有說明，關鍵字定義遵循 JSON Schema 的定義，且不添加任何額外語義；這包括 $schema、$id、$ref 和 $dynamicRef 等關鍵字是 URI 而非 URL。當 JSON Schema 指示行為由應用程式定義時（例如用於註釋），OAS 也將語義的定義延遲到使用 OpenAPI 文件的應用程式。

JSON Schema 關鍵字

OpenAPI Schema 物件方言定義為除了 JSON Schema 規格草案 2020-12 通用元架構中指定的詞彙表外，還需要OAS 基礎詞彙表。

此版本規格的 OpenAPI Schema 物件方言由 URI https://spec.openapis.org/oas/3.1/dialect/base（「OAS 方言架構 ID」）識別。

以下關鍵字取自 JSON Schema 規格，但其定義已由 OAS 擴充

• description - CommonMark 語法可用於豐富的文字表示。
• format - 請參閱資料類型格式以取得更多詳細資訊。在依賴 JSON Schema 定義的格式時，OAS 提供了一些額外的預定義格式。

除了構成 OAS 方言的 JSON Schema 關鍵字外，Schema 物件還支援來自任何其他詞彙表或完全任意的屬性中的關鍵字。

由於 OpenAPI 規格的基礎詞彙表以 false 的 $vocabulary 值包含在 OAS 方言中，因此 JSON Schema 實作可能會選擇將其定義的關鍵字視為未知關鍵字。OAS 基礎詞彙表包含以下關鍵字

固定欄位

欄位名稱	類型	描述
discriminator	Discriminator 物件	新增對多型性的支援。discriminator 用於確定預期有效負載要滿足的一組架構中的哪個。有關更多詳細資訊，請參閱組合與繼承。
xml	XML 物件	這只能用於屬性架構。它對根架構沒有影響。新增額外的中繼資料以描述此屬性的 XML 表示形式。
externalDocs	外部文件物件	此架構的額外外部文件。
example	任意	一個自由格式的欄位，用於包含此架構實例的範例。為了表示無法在 JSON 或 YAML 中自然表示的範例，可以使用字串值來包含範例，並在必要時使用逸出字元。 已過時： example 欄位已被棄用，改用 JSON Schema 的 examples 關鍵字。不建議使用 example，此規格的後續版本可能會將其移除。

此物件可以使用規格擴充功能進行擴充，但如上所述，額外的屬性可能會省略此物件中的 x- 前綴。

使用註釋進行擴充驗證

JSON Schema 草案 2020-12 支援收集註釋，包括將無法識別的關鍵字視為註釋。OAS 實作可能會使用此類註釋，包括未被識別為宣告的 JSON Schema 詞彙表一部分的擴充功能，作為進一步驗證的基礎。請注意，JSON Schema 草案 2020-12 並不要求擴充功能使用 x- 前綴。

非驗證約束關鍵字

format 關鍵字（使用預設 format-annotation 詞彙表時）以及contentMediaType、contentEncoding 和 contentSchema 關鍵字定義了資料上的約束，但被視為註釋而非直接驗證。擴充驗證是強制執行這些約束的一種方式。

驗證 readOnly 和 writeOnly

readOnly 和 writeOnly 關鍵字是註釋，因為 JSON Schema 不知道正在使用驗證的資料方式。這些關鍵字的驗證可以透過檢查註釋、讀取或寫入方向，以及（如果相關）欄位的目前值來完成。JSON Schema 驗證草案 2020-12 §9.4 定義了這些關鍵字的期望，包括資源（描述為「所有權機構」）可以忽略 readOnly 欄位或將其視為錯誤。

既是必要又是唯讀的欄位是一個例子，說明在 PUT 中忽略 readOnly: true 約束是有益的，尤其是當值沒有變更時。這允許在 GET 上正確要求該欄位，並且仍然將相同的表示形式和架構用於 PUT。即使唯讀欄位不是必要的，對用戶端來說，移除它們也很麻煩，特別是當 JSON 資料複雜或深度巢狀時。

請注意，readOnly 的行為與此規格的 3.0 版所指定的不同。

資料建模技術

組合與繼承（多型性）

OpenAPI 規格允許使用 JSON Schema 的 allOf 關鍵字來組合和擴充模型定義，實際上提供模型組合。allOf 採用物件定義的陣列，這些定義是獨立驗證的，但組合在一起構成單一物件。

雖然組合提供了模型的可擴充性，但它並不暗示模型之間的階層關係。為了支援多型性，OpenAPI 規格新增了discriminator 欄位。使用時，discriminator 指示屬性的名稱，該屬性提示預期哪個架構定義來驗證模型的結構。因此，discriminator 欄位必須是一個必要的欄位。有兩種方法可以為繼承的實例定義鑑別器的值。

• 使用架構名稱。
• 透過以新值覆寫屬性來覆寫架構名稱。如果存在新值，則此值優先於架構名稱。

通用（範本）資料結構

實作可能會支援使用 JSON Schema 的動態參考功能定義通用或範本資料結構

• $dynamicAnchor 識別一組可能的架構（包括預設預留位置架構），$dynamicRef 可以解析到這些架構
• $dynamicRef 解析為從架構進入點到參考的路徑上遇到的第一個符合的 $dynamicAnchor，如 JSON Schema 規格中所述

範例包含在下面的「Schema 物件範例」部分中，更多資訊可以在 Learn OpenAPI 網站的「動態參考」頁面找到。

帶有註解的列舉

Schema 物件的 enum 關鍵字不允許將描述或其他資訊與個別值關聯。

實作可能會支援識別 oneOf 或 anyOf，其中關鍵字陣列中的每個子架構都包含 const 關鍵字和諸如 title 或 description 之類的註釋，作為具有額外資訊的列舉類型。此模式超出 JSON Schema 所需的確切行為是實作定義的。

XML 建模

當將 JSON 定義轉換為 XML 時，xml 欄位允許額外的定義。XML 物件包含有關可用選項的其他資訊。

指定架構方言

對於工具來說，能夠確定任何給定資源希望使用哪個方言或元架構進行處理非常重要：JSON Schema Core、JSON Schema Validation、OpenAPI Schema 方言或某些自訂元架構。

$schema 關鍵字可能存在於任何屬於架構資源根目錄的 Schema 物件中，如果存在，則必須用於確定處理架構時應使用的方言。這允許使用符合預設草案 2020-12 支援以外的其他 JSON Schema 草案的 Schema 物件。工具必須支援OAS 方言架構 ID，並且可以支援 $schema 的其他值。

為了允許對 OAS 文件中包含的所有 Schema 物件使用不同的預設 $schema 值，可以在OpenAPI 物件中設定 jsonSchemaDialect 值。如果未設定此預設值，則必須對這些 Schema 物件使用 OAS 方言架構 ID。資源根目錄 Schema 物件中的 $schema 值始終覆寫任何預設值。

對於未設定 $schema 的獨立 JSON Schema 文件，或對於 OpenAPI 描述文件中不是完整文件的 Schema 物件，應假設方言為 OAS 方言。但是，為了獲得最大的互通性，建議 OpenAPI 描述作者在這些文件中透過 $schema 明確設定方言。

Schema 物件範例

基本範例

{
  "type": "string",
  "format": "email"
}

type: string
format: email

簡單模型

{
  "type": "object",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "#/components/schemas/Address"
    },
    "age": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
    }
  }
}

type: object
required:
  - name
properties:
  name:
    type: string
  address:
    $ref: '#/components/schemas/Address'
  age:
    type: integer
    format: int32
    minimum: 0

具有 Map/Dictionary 屬性的模型

對於簡單的字串到字串映射

{
  "type": "object",
  "additionalProperties": {
    "type": "string"
  }
}

type: object
additionalProperties:
  type: string

對於字串到模型映射

{
  "type": "object",
  "additionalProperties": {
    "$ref": "#/components/schemas/ComplexModel"
  }
}

type: object
additionalProperties:
  $ref: '#/components/schemas/ComplexModel'

具有帶註解列舉的模型

{
  "oneOf": [
    {
      "const": "RGB",
      "title": "Red, Green, Blue",
      "description": "Specify colors with the red, green, and blue additive color model"
    },
    {
      "const": "CMYK",
      "title": "Cyan, Magenta, Yellow, Black",
      "description": "Specify colors with the cyan, magenta, yellow, and black subtractive color model"
    }
  ]
}

oneOf:
  - const: RGB
    title: Red, Green, Blue
    description: Specify colors with the red, green, and blue additive color model
  - const: CMYK
    title: Cyan, Magenta, Yellow, Black
    description: Specify colors with the cyan, magenta, yellow, and black subtractive color model

具有範例的模型

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": ["name"],
  "examples": [
    {
      "name": "Puma",
      "id": 1
    }
  ]
}

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
  - name
examples:
  - name: Puma
    id: 1

具有組合的模型

{
  "components": {
    "schemas": {
      "ErrorModel": {
        "type": "object",
        "required": ["message", "code"],
        "properties": {
          "message": {
            "type": "string"
          },
          "code": {
            "type": "integer",
            "minimum": 100,
            "maximum": 600
          }
        }
      },
      "ExtendedErrorModel": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorModel"
          },
          {
            "type": "object",
            "required": ["rootCause"],
            "properties": {
              "rootCause": {
                "type": "string"
              }
            }
          }
        ]
      }
    }
  }
}

components:
  schemas:
    ErrorModel:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf:
        - $ref: '#/components/schemas/ErrorModel'
        - type: object
          required:
            - rootCause
          properties:
            rootCause:
              type: string

具有多型性支援的模型

{
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "discriminator": {
          "propertyName": "petType"
        },
        "properties": {
          "name": {
            "type": "string"
          },
          "petType": {
            "type": "string"
          }
        },
        "required": ["name", "petType"]
      },
      "Cat": {
        "description": "A representation of a cat. Note that `Cat` will be used as the discriminating value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "huntingSkill": {
                "type": "string",
                "description": "The measured skill for hunting",
                "default": "lazy",
                "enum": ["clueless", "lazy", "adventurous", "aggressive"]
              }
            },
            "required": ["huntingSkill"]
          }
        ]
      },
      "Dog": {
        "description": "A representation of a dog. Note that `Dog` will be used as the discriminating value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "packSize": {
                "type": "integer",
                "format": "int32",
                "description": "the size of the pack the dog is from",
                "default": 0,
                "minimum": 0
              }
            },
            "required": ["packSize"]
          }
        ]
      }
    }
  }
}

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
      properties:
        name:
          type: string
        petType:
          type: string
      required:
        - name
        - petType
    Cat: # "Cat" will be used as the discriminating value
      description: A representation of a cat
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            huntingSkill:
              type: string
              description: The measured skill for hunting
              enum:
                - clueless
                - lazy
                - adventurous
                - aggressive
          required:
            - huntingSkill
    Dog: # "Dog" will be used as the discriminating value
      description: A representation of a dog
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            packSize:
              type: integer
              format: int32
              description: the size of the pack the dog is from
              default: 0
              minimum: 0
          required:
            - packSize

通用資料結構模型

{
  "components": {
    "schemas": {
      "genericArrayComponent": {
        "$id": "fully_generic_array",
        "type": "array",
        "items": {
          "$dynamicRef": "#generic-array"
        },
        "$defs": {
          "allowAll": {
            "$dynamicAnchor": "generic-array"
          }
        }
      },
      "numberArray": {
        "$id": "array_of_numbers",
        "$ref": "fully_generic_array",
        "$defs": {
          "numbersOnly": {
            "$dynamicAnchor": "generic-array",
            "type": "number"
          }
        }
      },
      "stringArray": {
        "$id": "array_of_strings",
        "$ref": "fully_generic_array",
        "$defs": {
          "stringsOnly": {
            "$dynamicAnchor": "generic-array",
            "type": "string"
          }
        }
      },
      "objWithTypedArray": {
        "$id": "obj_with_typed_array",
        "type": "object",
        "required": ["dataType", "data"],
        "properties": {
          "dataType": {
            "enum": ["string", "number"]
          }
        },
        "oneOf": [{
          "properties": {
            "dataType": {"const": "string"},
            "data": {"$ref": "array_of_strings"}
          }
        }, {
          "properties": {
            "dataType": {"const": "number"},
            "data": {"$ref": "array_of_numbers"}
          }
        }]
      }
    }
  }
}

components:
  schemas:
    genericArrayComponent:
      $id: fully_generic_array
      type: array
      items:
        $dynamicRef: '#generic-array'
      $defs:
        allowAll:
          $dynamicAnchor: generic-array
    numberArray:
      $id: array_of_numbers
      $ref: fully_generic_array
      $defs:
        numbersOnly:
          $dynamicAnchor: generic-array
          type: number
    stringArray:
      $id: array_of_strings
      $ref: fully_generic_array
      $defs:
        stringsOnly:
          $dynamicAnchor: generic-array
          type: string
    objWithTypedArray:
      $id: obj_with_typed_array
      type: object
      required:
      - dataType
      - data
      properties:
        dataType:
          enum:
          - string
          - number
      oneOf:
      - properties:
          dataType:
            const: string
          data:
            $ref: array_of_strings
      - properties:
          dataType:
            const: number
          data:
            $ref: array_of_numbers

Discriminator 物件

當請求主體或回應有效負載可能是多種不同架構之一時，Discriminator 物件會提供有關文件的預期架構的提示。此提示可用於協助序列化、反序列化和驗證。Discriminator 物件透過隱式或明確地將已命名屬性的可能值與替代架構關聯來執行此操作。

請注意，discriminator 不得變更架構的驗證結果。

固定欄位

欄位名稱	類型	描述
propertyName	string	必要。有效負載中將保留鑑別值的屬性名稱。此屬性應該在有效負載架構中是必要的，因為當屬性不存在時的行為是未定義的。
mapping	Map[string, string]	一個物件，用於保存有效負載值與架構名稱或 URI 參考之間的映射。

此物件可以透過規格擴充來擴充。

使用辨別器物件的條件

辨別器物件僅在使用複合關鍵字 oneOf、anyOf、allOf 時合法。

在 oneOf 和 anyOf 的使用案例中，當這些關鍵字與 discriminator 相鄰時，必須明確列出所有可能的架構。

為了避免冗餘，辨別器可以新增到父架構定義中，並且所有通過 allOf 建構在父架構上的架構都可以用作替代架構。

discriminator 的 allOf 形式僅適用於非驗證使用案例；使用具有此形式 discriminator 的父架構進行驗證不會執行對子架構的搜尋或以任何方式在驗證中使用它們。這是因為 discriminator 無法更改驗證結果，並且沒有標準的 JSON Schema 關鍵字將父架構連接到子架構。

任何未在上述描述的 oneOf、anyOf、allOf 和 discriminator 的配置的行為都是未定義的。

將值映射到架構的選項

在 元件物件下，以 propertyName 命名的屬性的值被用作關聯架構的名稱，除非該值存在 mapping。mapping 條目將特定屬性值映射到不同的架構元件名稱，或映射到由 URI 識別的架構。當使用隱式或顯式架構元件名稱時，不會考慮內聯 oneOf 或 anyOf 子架構。mapping 值既是有效的架構名稱又是有效的相對 URI 參考的行為是實作定義的，但建議將其視為架構名稱。為了確保所有實作將模稜兩可的值（例如 "foo"）視為相對 URI 參考，作者必須在其前面加上 "." 路徑片段（例如 "./foo"）。

映射鍵必須是字串值，但工具可能會將回應值轉換為字串以進行比較。但是，此類轉換的確切性質是實作定義的。

範例

對於這些範例，假設所有架構都在 OAD 的輸入文件中；關於參考文件中 discriminator 的處理，請參閱解析隱式連接。

在 OAS 3.x 中，可以將回應有效負載描述為恰好是任意數量的類型之一

MyResponseType:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Lizard'

這表示通過驗證，有效負載必須與 Cat、Dog 或 Lizard 描述的架構之一完全匹配。反序列化 oneOf 可能是一項昂貴的操作，因為它需要確定哪個架構與有效負載匹配，因此應在反序列化中使用。anyOf 架構也存在此問題。discriminator 可以用作「提示」來提高選擇匹配架構的效率。discriminator 欄位無法更改 oneOf 的驗證結果，它只能幫助提高反序列化的效率並提供更好的錯誤訊息。我們可以指定確切的欄位，告訴我們預期哪個架構匹配實例

MyResponseType:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Lizard'
  discriminator:
    propertyName: petType

現在的期望是，回應有效負載中必須存在名稱為 petType 的屬性，並且該值將對應於 OpenAPI 描述中定義的架構的名稱。因此，回應有效負載

{
  "id": 12345,
  "petType": "Cat"
}

將指示預期 Cat 架構與此有效負載匹配。

在 discriminator 欄位的值與架構名稱不匹配或無法進行隱式映射的情況下，可以使用可選的 mapping 定義

MyResponseType:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Lizard'
    - $ref: https://gigantic-server.com/schemas/Monster/schema.json
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      monster: https://gigantic-server.com/schemas/Monster/schema.json

這裡的辨別值 dog 將會映射到架構 #/components/schemas/Dog，而不是預設（隱式）值 #/components/schemas/dog。如果辨別值與隱式或顯式映射不匹配，則無法確定架構，且驗證應該失敗。

當與 anyOf 建構結合使用時，使用辨別器可以避免序列化器/反序列化器的歧義，在這些情況下，多個架構可能滿足單個有效負載。

此範例顯示 allOf 的用法，這避免了需要在父項中引用所有子架構

components:
  schemas:
    Pet:
      type: object
      required:
        - petType
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        mapping:
          dog: Dog
    Cat:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          # all other properties specific to a `Cat`
          properties:
            name:
              type: string
    Dog:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          # all other properties specific to a `Dog`
          properties:
            bark:
              type: string
    Lizard:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          # all other properties specific to a `Lizard`
          properties:
            lovesRocks:
              type: boolean

針對 Pet 架構驗證，像這樣的有效負載

{
  "petType": "Cat",
  "name": "Misty"
}

將指示預期 #/components/schemas/Cat 架構與此匹配。同樣，此有效負載

{
  "petType": "dog",
  "bark": "soft"
}

將映射到 #/components/schemas/Dog，因為 mapping 元素中的 dog 條目映射到 Dog，這是 #/components/schemas/Dog 的架構名稱。

XML 物件

一個中繼資料物件，允許更精細的 XML 模型定義。

當使用陣列時，XML 元素名稱不會被推斷（對於單數/複數形式），並且應該使用 name 欄位新增該資訊。請參閱預期行為的範例。

固定欄位

欄位名稱	類型	描述
name	string	取代用於描述的架構屬性的元素/屬性名稱。當在 items 中定義時，它將影響清單中個別 XML 元素的名稱。當與類型為 "array"（在 items 之外）的 type 一起定義時，如果且僅當 wrapped 為 true 時，它才會影響包裝元素。如果 wrapped 為 false，則會忽略它。
namespace	string	命名空間定義的 URI。值必須是非相對 URI 的形式。
prefix	string	用於 name 的前綴。
attribute	布林值	宣告屬性定義轉譯為屬性而非元素。預設值為 false。
wrapped	布林值	可能僅用於陣列定義。表示陣列是包裝的（例如，<books><book/><book/></books>）還是未包裝的（<book/><book/>）。預設值為 false。此定義僅在與類型為 "array"（在 items 之外）的 type 一起定義時才生效。

此物件可以透過規格擴充來擴充。

namespace 欄位的目的是為了匹配 XML 命名空間的語法，儘管有一些注意事項

• 此規格的 3.1.0、3.0.3 和更早版本錯誤地使用「絕對 URI」而不是「非相對 URI」，因此使用包含片段的命名空間的作者應仔細檢查工具支援。
• XML 允許但不鼓勵相對 URI 參考，而此規格完全禁止它們。
• XML 1.1 允許 IRI（RFC3987）作為命名空間，並指定比較命名空間時不進行任何編碼或解碼，這表示為滿足此規格的 URI 語法要求而編碼的 IRI 無法與原始 IRI 進行比較。

XML 物件範例

以下每個範例代表 架構物件中 properties 關鍵字的值，為了簡潔起見，已省略該架構物件。properties 值的 JSON 和 YAML 表示形式後跟為顯示的單一屬性產生的 XML 表示範例。

沒有 XML 元素

基本字串屬性

{
  "animals": {
    "type": "string"
  }
}

animals:
  type: string

<animals>...</animals>

基本字串陣列屬性（預設情況下 wrapped 為 false）

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}

animals:
  type: array
  items:
    type: string

<animals>...</animals>
<animals>...</animals>
<animals>...</animals>

XML 名稱取代

{
  "animals": {
    "type": "string",
    "xml": {
      "name": "animal"
    }
  }
}

animals:
  type: string
  xml:
    name: animal

<animal>...</animal>

XML 屬性、前綴和命名空間

在此範例中，顯示了完整的模型定義。

{
  "Person": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32",
        "xml": {
          "attribute": true
        }
      },
      "name": {
        "type": "string",
        "xml": {
          "namespace": "https://example.com/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}

Person:
  type: object
  properties:
    id:
      type: integer
      format: int32
      xml:
        attribute: true
    name:
      type: string
      xml:
        namespace: https://example.com/schema/sample
        prefix: sample

<Person id="123">
    <sample:name xmlns:sample="https://example.com/schema/sample">example</sample:name>
</Person>

XML 陣列

變更元素名稱

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal

<animal>value</animal>
<animal>value</animal>

外部 name 欄位對 XML 沒有影響

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens"
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens

<animal>value</animal>
<animal>value</animal>

即使陣列被包裝，如果未明確定義名稱，則內部和外部都將使用相同的名稱

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    wrapped: true

<animals>
  <animals>value</animals>
  <animals>value</animals>
</animals>

為了克服上述範例中的命名問題，可以使用以下定義

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    wrapped: true

<animals>
  <animal>value</animal>
  <animal>value</animal>
</animals>

同時影響內部和外部名稱

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens
    wrapped: true

<aliens>
  <animal>value</animal>
  <animal>value</animal>
</aliens>

如果我們變更外部元素但不變更內部元素

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    name: aliens
    wrapped: true

<aliens>
  <aliens>value</aliens>
  <aliens>value</aliens>
</aliens>

安全方案物件

定義操作可以使用的安全方案。

支援的方案有 HTTP 驗證、API 金鑰（可以是標頭、Cookie 參數或查詢參數）、相互 TLS（使用用戶端憑證）、OAuth2 的常見流程（隱式、密碼、用戶端憑證和授權碼），如 RFC6749 和 [[OpenID-Connect-Core]] 中所定義。請注意，截至 2020 年，OAuth 2.0 安全最佳實務即將棄用隱式流程。對於大多數使用案例，建議使用帶有 PKCE 的授權碼授權流程。

固定欄位

欄位名稱	類型	適用於	描述
type	string	任意	必要。安全方案的類型。有效值為 "apiKey"、"http"、"mutualTLS"、"oauth2"、"openIdConnect"。
description	string	任意	安全方案的描述。 CommonMark 語法可以用於富文字表示。
name	string	apiKey	必要。要使用的標頭、查詢或 Cookie 參數的名稱。
in	string	apiKey	必要。API 金鑰的位置。有效值為 "query"、"header" 或 "cookie"。
scheme	string	http	必要。要在 RFC7235 中定義的授權標頭中使用的 HTTP 驗證方案的名稱。使用的值應該在 IANA 驗證方案註冊中註冊。該值不區分大小寫，如 RFC7235 中所定義。
bearerFormat	string	http（"bearer"）	提示用戶端如何格式化持有者權杖。持有者權杖通常由授權伺服器產生，因此此資訊主要用於文件編寫目的。
flows	OAuth 流程物件	oauth2	必要。一個物件，包含支援的流程類型的配置資訊。
openIdConnectUrl	string	openIdConnect	必要。用於探索 [[OpenID-Connect-Discovery]] 提供者中繼資料的已知 URL。

此物件可以透過規格擴充來擴充。

安全方案物件範例

基本驗證範例

{
  "type": "http",
  "scheme": "basic"
}

type: http
scheme: basic

API 金鑰範例

{
  "type": "apiKey",
  "name": "api-key",
  "in": "header"
}

type: apiKey
name: api-key
in: header

JWT 持有者範例

{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT"
}

type: http
scheme: bearer
bearerFormat: JWT

相互 TLS 範例

{
  "type": "mutualTLS",
  "description": "Cert must be signed by example.com CA"
}

type: mutualTLS
description: Cert must be signed by example.com CA

隱式 OAuth2 範例

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

OAuth 流程物件

允許配置支援的 OAuth 流程。

固定欄位

欄位名稱	類型	描述
implicit	OAuth 流程物件	OAuth 隱式流程的配置
password	OAuth 流程物件	OAuth 資源擁有者密碼流程的配置
clientCredentials	OAuth 流程物件	OAuth 用戶端憑證流程的配置。之前在 OpenAPI 2.0 中稱為 application。
authorizationCode	OAuth 流程物件	OAuth 授權碼流程的配置。之前在 OpenAPI 2.0 中稱為 accessCode。

此物件可以透過規格擴充來擴充。

OAuth 流程物件

支援的 OAuth 流程的配置詳細資訊

固定欄位

欄位名稱	類型	適用於	描述
authorizationUrl	string	oauth2（"implicit"、"authorizationCode"）	必要。用於此流程的授權 URL。這必須是 URL 的形式。OAuth2 標準要求使用 TLS。
tokenUrl	string	oauth2（"password"、"clientCredentials"、"authorizationCode"）	必要。用於此流程的權杖 URL。這必須是 URL 的形式。OAuth2 標準要求使用 TLS。
refreshUrl	string	oauth2	用於取得重新整理權杖的 URL。這必須是 URL 的形式。OAuth2 標準要求使用 TLS。
scopes	Map[string, string]	oauth2	必要。OAuth2 安全方案的可用的範圍。範圍名稱和其簡短描述之間的映射。該映射可能為空。

此物件可以透過規格擴充來擴充。

OAuth 流程物件範例

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    },
    "authorizationCode": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "tokenUrl": "https://example.com/api/oauth/token",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
  authorizationCode:
    authorizationUrl: https://example.com/api/oauth/dialog
    tokenUrl: https://example.com/api/oauth/token
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

安全需求物件

列出執行此操作所需的安全性方案。每個屬性使用的名稱必須與元件物件下的安全性方案中宣告的安全性方案相對應。

安全需求物件可以參考多個安全性方案，在這種情況下，必須滿足所有方案才能授權請求。這使得可以支援需要多個查詢參數或 HTTP 標頭來傳達安全性資訊的場景。

當 security 欄位在 OpenAPI 物件或 操作物件上定義，並且包含多個安全需求物件時，只需滿足列表中其中一個條目即可授權請求。這使得可以支援 API 允許多個獨立安全性方案的場景。

空的安全性需求物件 ({}) 表示支援匿名存取。

模式化欄位

欄位模式	類型	描述
{name}	[string]	每個名稱必須對應於在元件物件下的安全性方案中宣告的安全性方案。如果安全性方案的類型為 "oauth2" 或 "openIdConnect"，則該值為執行所需範圍名稱的列表，如果授權不需要指定的範圍，則列表可以為空。對於其他安全性方案類型，陣列可能包含執行所需的角色名稱列表，但這些角色名稱沒有以其他方式定義或帶內交換。

安全需求物件範例

另請參閱附錄 F：解析參考文件中安全需求，其中包含在多文件 OpenAPI 描述中使用安全需求物件的範例。

非 OAuth2 安全需求

{
  "api_key": []
}

api_key: []

OAuth2 安全需求

{
  "petstore_auth": ["write:pets", "read:pets"]
}

petstore_auth:
  - write:pets
  - read:pets

可選的 OAuth2 安全性

可選的 OAuth2 安全性，如同在OpenAPI 物件或操作物件中定義的那樣

{
  "security": [
    {},
    {
      "petstore_auth": ["write:pets", "read:pets"]
    }
  ]
}

security:
  - {}
  - petstore_auth:
      - write:pets
      - read:pets

規格擴充

雖然 OpenAPI 規格試圖容納大多數使用案例，但可以添加其他資料以在特定點擴充規格。

擴充屬性實作為以 x- 為前綴的模式欄位。

欄位模式	類型	描述
^x-	任意	允許對 OpenAPI 綱要進行擴充。欄位名稱必須以 x- 開頭，例如，x-internal-id。以 x-oai- 和 x-oas- 開頭的欄位名稱保留給 OpenAPI Initiative 定義的用途。該值可以是任何有效的 JSON 值（null、基本型別、陣列或物件）。

OpenAPI Initiative 維護多個 [[OpenAPI-Registry|擴充註冊表]]，包括個別擴充關鍵字和擴充關鍵字命名空間的註冊表。

擴充是證明規格建議新增內容可行性的最佳方式之一。因此，建議實作設計為可擴充，以支援社群實驗。

對任何一個擴充的支援是可選的，對一個擴充的支援並不意味著對其他擴充的支援。

安全性篩選

OpenAPI 規格中的某些物件可能會被宣告並保持為空，或者被完全刪除，即使它們本質上是 API 文件中的核心。

這樣做的理由是允許對文件進行額外的存取控制層。雖然這不是規格本身的一部分，但某些函式庫可能會選擇根據某種形式的驗證/授權來允許存取文件的某些部分。

以下是兩個範例

1. 路徑物件可能會存在但為空。這可能與直覺相反，但這可能會告訴檢視者他們到達了正確的位置，但無法存取任何文件。他們仍然可以存取至少資訊物件，其中可能包含有關驗證的其他資訊。
2. 路徑項目物件可能為空。在這種情況下，檢視者會知道該路徑存在，但將無法看到其任何操作或參數。這與從路徑物件隱藏路徑本身不同，因為使用者會知道它的存在。這允許文件提供者精細地控制檢視者可以看到的內容。

安全性考量

OpenAPI 描述格式

OpenAPI 描述結合使用了 JSON、YAML 和 JSON 綱要，因此也具有它們的安全性考量。

• JSON
• YAML
• JSON 綱要核心
• JSON 綱要驗證

工具和使用案例

此外，OpenAPI 描述由各種工具處理，用於許多不同的目的，例如用戶端程式碼產生、文件產生、伺服器端路由和 API 測試。OpenAPI 描述作者必須考量 OpenAPI 描述可能被使用的場景中的風險。

安全性方案

OpenAPI 描述描述了用於保護其定義的資源的安全性方案。可用的安全性方案提供不同程度的保護。資料的敏感度和安全漏洞的潛在影響等因素應指導 API 資源的安全性方案選擇。為了與現有的 API 相容，支援一些安全性方案，例如基本身份驗證和 OAuth 隱式流程。但是，將它們納入 OpenAPI 中並不表示認可它們的使用，特別是用於高度敏感的資料或操作。

處理外部資源

OpenAPI 描述可能包含對外部資源的參考，這些參考可能由使用工具自動取消參考。外部資源可能託管在可能不受信任的不同網域上。

處理參考週期

OpenAPI 描述中的參考可能會導致週期。工具必須偵測並處理週期以防止資源耗盡。

Markdown 和 HTML 清理

某些欄位允許使用 Markdown，其中可能包含 HTML，包括腳本。工具應負責適當地清理 Markdown。

附錄 A：修訂歷史

版本	日期	註解
3.1.1	2024-10-24	OpenAPI 規格 3.1.1 的修補程式版本
3.1.0	2021-02-15	OpenAPI 規格 3.1.0 的發布
3.1.0-rc1	2020-10-08	3.1 規格的 rc1
3.1.0-rc0	2020-06-18	3.1 規格的 rc0
3.0.4	2024-10-24	OpenAPI 規格 3.0.4 的修補程式版本
3.0.3	2020-02-20	OpenAPI 規格 3.0.3 的修補程式版本
3.0.2	2018-10-08	OpenAPI 規格 3.0.2 的修補程式版本
3.0.1	2017-12-06	OpenAPI 規格 3.0.1 的修補程式版本
3.0.0	2017-07-26	OpenAPI 規格 3.0.0 的發布
3.0.0-rc2	2017-06-16	3.0 規格的 rc2
3.0.0-rc1	2017-04-27	3.0 規格的 rc1
3.0.0-rc0	2017-02-28	3.0 規格的實作人員草案
2.0	2015-12-31	將 Swagger 2.0 捐贈給 OpenAPI Initiative
2.0	2014-09-08	Swagger 2.0 的發布
1.2	2014-03-14	正式文件的初始發布。
1.1	2012-08-22	Swagger 1.1 的發布
1.0	2011-08-10	Swagger 規格的首次發布

附錄 B：資料類型轉換

將類型化資料序列化為純文字，這可能發生在 text/plain 訊息主體或 multipart 部分中，以及 URL 查詢字串或訊息主體中的 application/x-www-form-urlencoded 格式中，涉及到顯著的實作或應用程式定義行為。

綱要物件根據JSON 綱要資料模型驗證資料，該模型僅識別四種基本資料類型：字串（僅在 UTF-8 中具有廣泛的互通性）、數字、布林值和 null。值得注意的是，整數不是與其他數字不同的類型，type: "integer" 是數學上定義的便利方式，而不是基於任何字串表示形式中是否存在小數點。

參數物件、標頭物件和編碼物件提供了一些功能來控制如何排列陣列或物件類型的值。它們還可以用於控制如何進一步編碼字串以避免保留或非法字元。但是，沒有通用的規範將綱要驗證的非 UTF-8 基本資料類型（或整個陣列或物件）轉換為字串。

有兩種情況提供了基於標準的指導

• RFC3987 提供了將非 Unicode 字串轉換為 UTF-8 的指導，尤其是在 URI 的上下文中（並以此類推，使用相同編碼規則的表單媒體類型）
• RFC6570 指定了哪些值（包括但不限於 null）被視為未定義，因此在基於該規範進行序列化時，在展開過程中會受到特殊處理

RFC6570 的實作通常有自己轉換非字串值的約定，但這些是特定於實作的，並且不是由 RFC 本身定義的。這是 OpenAPI 規格將這些轉換保留為實作定義的原因之一：它允許使用 RFC6570 實作，無論它們如何選擇執行轉換。

為了更精確地控制數字、布林值和 null（或 RFC6570 認為未定義的其他值）的序列化，綱要可以定義為 type: "string"，並使用 pattern、enum、format 和其他關鍵字來約束，以傳達應用程式在綱要驗證之前必須如何預先轉換其資料。產生的字串不需要任何進一步的類型轉換。

format 關鍵字可以協助序列化。某些格式（例如 date-time）是明確的，而其他格式（例如decimal，在格式註冊表中）則不太明確。但是，必須謹慎使用 format，以確保所有相關工具都支援特定的格式，因為未識別的格式會被忽略。

要求以預先格式化、綱要驗證的字串作為輸入也提高了往返互通性，因為並非所有程式設計語言和環境都支援相同的資料類型。

附錄 C：使用基於 RFC6570 的序列化

序列化根據RFC6570 URI 範本在三種情境中定義

物件	條件
參數物件	當 schema 存在時
標頭物件	當 schema 存在時
Encoding 物件	當編碼為 application/x-www-form-urlencoded 時，並且使用 style、explode 或 allowReserved 中的任何一個時

本規範的實作**可以**使用 RFC6570 的實作來執行變數展開，但有一些注意事項。

請注意，當使用 style: "form" RFC6570 展開來產生 application/x-www-form-urlencoded HTTP 訊息主體時，必須移除產生的 ? 前綴，以符合 URI 查詢字串語法。

當使用 style 和類似的關鍵字來產生 multipart/form-data 主體時，查詢字串名稱會放在 Content-Disposition 部份標頭的 name 參數中，而值則放在相應的部份主體中；不會使用 ?、= 和 & 字元。請注意，雖然 RFC7578 允許在「檔案名稱」中使用 [[RFC3986]] 百分比編碼，但它並未處理格式內百分比編碼的使用。RFC7578 詳細討論了 multipart/form-data 的字元集和編碼問題，建議 OpenAPI 描述的作者在決定使用基於 RFC6570 的序列化與此媒體類型時，仔細閱讀此指南。

另請注意，並非所有 RFC6570 的實作都支援所有四個層級的運算子，而這些運算子都是完全支援 OpenAPI 規範的用法所必需的。使用支援層級較低的實作將需要額外手動建構 URI 範本，以解決這些限制。

欄位與 RFC6570 運算子之間的等效性

某些欄位值會轉譯為 RFC6570 運算子（或沒有運算子）

欄位	值	等效
style	"simple"	不適用
style	"matrix"	; 前綴運算子
style	"label"	. 前綴運算子
style	"form"	? 前綴運算子
allowReserved	false	不適用
allowReserved	true	+ 前綴運算子
explode	false	不適用
explode	true	* 修飾詞後綴

多個 style: "form" 參數等效於使用 ? 前綴運算子的單個 RFC6570 變數列表

parameters:
- name: foo
  in: query
  schema:
    type: object
  explode: true
- name: bar
  in: query
  schema:
    type: string

此範例等效於 RFC6570 的 {?foo*,bar}，而不是 {?foo*}{&bar}。後者是有問題的，因為如果未定義 foo，則結果將是無效的 URI。& 前綴運算子在參數物件中沒有等效的表示法。

請注意，RFC6570 並未指定除了 explode 所處理的單一層級之外的複合值行為。在未明確指定行為的情況下使用物件或陣列的結果，由實作定義。

參數值中的分隔符號

RFC6570 展開所使用的分隔符號，例如用於將陣列或物件值與 style: "simple" 連接的 ,，只要 allowReserved 為 false，都會自動進行百分比編碼。請注意，由於 RFC6570 沒有定義基於 URI 範本解析變數的方法，因此使用者必須先按分隔符號分割值，然後再對可能包含分隔符號字元的值進行百分比解碼。

當 allowReserved 為 true 時，百分比編碼（在將值與分隔符號連接之前）和百分比解碼（在按分隔符號分割之後）都必須在正確的時間手動完成。

請參閱附錄 E，以獲取關於處理沒有 RFC6570 等效的 style 值的分隔符號的額外指南，這些值在用作分隔符號時已經需要進行百分比編碼。

非 RFC6570 欄位值和組合

沒有直接 RFC6570 等效的組態也應該根據 RFC6570 處理。實作**可以**使用 RFC6570 常規或保留展開（基於 allowReserved）為個別名稱和值建立正確分隔的 URI 範本。

這包括

• 樣式 pipeDelimited、spaceDelimited 和 deepObject，它們根本沒有等效的表示法
• 樣式 form 與 allowReserved: true 的組合，不允許這樣做，因為一次只能使用一個前綴運算子
• 任何不是合法的 RFC6570 變數名稱的參數名稱

參數物件的 name 欄位具有比 RFC6570 變數名稱語法 更寬鬆的語法。在 URI 範本中使用之前，必須對包含 RFC6570 允許的變數字元集之外的字元的參數名稱進行百分比編碼。

範例

假設我們想在表單查詢字串中使用以下資料，其中 formulas 已展開，而 words 未展開

formulas:
  a: x+y
  b: x/y
  c: x^y
words:
- math
- is
- fun

RFC6570 等效展開

此參數物件陣列使用常規的 style: "form" 展開，完全由 RFC6570 支援

parameters:
- name: formulas
  in: query
  schema:
    type: object
    additionalProperties:
      type: string
  explode: true
- name: words
  in: query
  schema:
    type: array
    items:
      type: string

這會轉譯為以下 URI 範本

{?formulas*,words}

當使用先前給定的資料展開時，我們得到

?a=x%2By&b=x%2Fy&c=x%5Ey&words=math,is,fun

使用非 RFC6570 支援的選項進行展開

但現在假設（由於某些原因），我們真的希望 b 公式中的 / 在查詢字串中按原樣顯示，並且我們希望我們的單字像書面短語一樣以空格分隔。為此，我們將在 formulas 中新增 allowReserved: true，並將 words 的 style 變更為 "spaceDelimited"

parameters:
- name: formulas
  in: query
  schema:
    type: object
    additionalProperties:
      type: string
  explode: true
  allowReserved: true
- name: words
  in: query
  style: spaceDelimited
  explode: false
  schema:
    type: array
    items:
      type: string

我們無法組合 ? 和 + RFC6570 前綴，並且 RFC6570 無法將 , 分隔符號取代為空格字元。因此，我們需要重新建構資料，以符合手動建構的 URI 範本，該範本將所有部分傳遞到正確的展開類型。

這是其中一個範本，它使用一個虛構的慣例，為單字值中的第一個條目使用 words.0，為第二個條目使用 words.1，為第三個條目使用 words.2

?a={+a}&b={+b}&c={+c}&words={words.0} {words.1} {words.2}

RFC6570 提及使用 .「指示子結構中的名稱層次結構」，但並未定義任何特定的命名慣例或行為。由於 . 的用法不是自動的，因此我們需要為這個新的範本建構適當的輸入結構。

我們還需要預先處理 formulas 的值，因為雖然 RFC3986 允許在查詢字串中使用 / 和大多數其他保留字元，但 [、] 和 # 不允許，而 &、= 和 + 在 application/x-www-form-urlencoded 格式中都具有 特殊行為，這也是我們在查詢字串中使用的格式。

設定 allowReserved: true 並**不**會使不允許在 URI 中使用的保留字元變成允許的字元，它只是允許它們在展開時未經變更地傳遞。因此，任何工具仍然需要對這些字元進行百分比編碼，因為保留展開不會這樣做，但它*會*讓百分比編碼的三個字元組保持不變。另請參閱附錄 E，以獲取關於百分比編碼和表單媒體類型的更多指南，包括關於處理參數名稱和值中 spaceDelimited、pipeDelimited 和 deepObject 的分隔符號字元的指南。

因此，這是我們的資料結構，它安排了名稱和值以適合上述範本，其中 formulas 的值已預先進行百分比編碼 []#&=+ （儘管在此範例中僅出現 +）

a: x%2By
b: x/y
c: x^y
words.0: math
words.1: is
words.2: fun

使用我們重新建構的資料展開我們手動組裝的範本，會產生以下查詢字串

?a=x%2By&b=x/y&c=x%5Ey&words=math%20is%20fun

/ 和預先進行百分比編碼的 %2B 都保持不變，但不允許的 ^ 字元（在值內）和空格字元（在範本中，但在展開的變數之外）都進行了百分比編碼。

未定義的值和手動 URI 範本建構

在手動建構範本以正確處理 RFC6570 視為*未定義*的值時，必須小心

formulas: {}
words:
- hello
- world

將此資料與我們原始的 RFC6570 友好的 URI 範本 {?formulas*,words} 一起使用，會產生以下結果

?words=hello,world

這表示手動建構的 URI 範本和重新建構的資料需要完全省略 formulas 物件，以便 words 參數成為查詢字串中的第一個且唯一的參數。

重新建構的資料

words.0: hello
words.1: world

手動建構的 URI 範本

?words={words.0} {words.1}

結果

?words=hello%20world

非法變數名稱作為參數名稱

在此範例中，心形表情符號在 URI 範本名稱（或 URI）中是不合法的

parameters:
- name: ❤️
  in: query
  schema:
    type: string

我們不能僅將 ❤️: "love!" 傳遞給 RFC6570 實作。相反地，我們必須在資料和 URI 範本中預先對名稱進行百分比編碼（這是一個六位元組 UTF-8 序列）

"%E2%9D%A4%EF%B8%8F": love!

{?%E2%9D%A4%EF%B8%8F}

這將展開為結果

?%E2%9D%A4%EF%B8%8F=love%21

附錄 D：序列化標頭和 Cookie

RFC6570 的百分比編碼行為並不總是適用於 in: "header" 和 in: "cookie" 參數。在許多情況下，使用具有諸如 text/plain 之類媒體類型的 content 更為合適，並要求應用程式組裝正確的字串。

對於使用 RFC8941 結構化欄位語法的 RFC6265 Cookie 和 HTTP 標頭，非 ASCII 內容會使用 base64 編碼 (contentEncoding: "base64") 來處理。請注意，標準的 base64 編碼字母包含 RFC6570 展開會進行百分比編碼的非 URL 安全字元；不建議通過兩種編碼來序列化值。雖然 contentEncoding 也支援 URL 安全的 base64url 編碼，但標頭和 Cookie 的 RFC 並未提及此編碼。

大多數 HTTP 標頭早於結構化欄位語法，而對其語法和編碼規則的全面評估超出了本規範的範圍。雖然 RFC8187 建議對 HTTP（標頭或追蹤器）欄位參數進行百分比編碼，但這些參數會出現在 ; 字元之後。使用 style: "simple"，該分隔符號本身會進行百分比編碼，從而違反了通用的 HTTP 欄位語法。

將 style: "form" 與 in: "cookie" 一起使用對於單個值而言是不明確的，而對於多個值而言是不正確的。無論多個值是否為使用 explode: true 的結果，都是如此。

此樣式被指定為等效於 RFC6570 表單展開，其中包括 ? 字元（請參閱附錄 C 了解更多詳細資訊），這不是 Cookie 語法的一部分。但是，本規範過去版本中此樣式的範例未包含 ? 前綴，這表示比較不精確。由於依賴 RFC6570 實作的實作和基於樣式範例執行自訂序列化的實作會產生不同的結果，因此兩個結果中哪一個是正確的由實作定義。

對於多個值，style: "form" 始終不正確，因為 Cookie 中的 name=value 對以 ;（分號後跟一個空格字元）而不是 & 分隔。

附錄 E：百分比編碼和表單媒體類型

注意： 在本節中，為了方便閱讀，application/x-www-form-urlencoded 和 multipart/form-data 這兩種媒體類型將分別簡寫為 form-urlencoded 和 form-data。

百分比編碼（Percent-encoding）用於 URI 和從 URI 衍生語法的媒體類型。此過程涉及三組字元，這些字元的名稱在不同規範中有所不同，但在本節中定義如下：

• 未保留 (unreserved) 字元不需要進行百分比編碼；雖然對它們進行百分比編碼是安全的，但這樣做會產生一個未標準化的 URI。
• 已保留 (reserved) 字元在 URI 語法中具有特殊行為（例如，作為組件的分隔符），或者為其他需要定義特殊行為的規範保留（例如，form-urlencoded 為 =、& 和 + 定義了特殊行為）。
• 不安全 (unsafe) 字元在某些環境中解析 URI 時已知會引起問題。

除非另有說明，否則本節使用 RFC3986 對已保留和未保留的定義，並將不安全字元集定義為不包含在其中任一集合中的所有字元。

百分比編碼和 form-urlencoded

每個 URI 組件（例如查詢字串）都將一些已保留字元視為不安全，因為它們是組件之間的分隔符（例如 #），或者（在 [ 和 ] 的情況下）在歷史上被認為是全局不安全的，但後來被賦予了在有限目的下的保留狀態。

在組件中沒有定義特殊含義的已保留字元可以保持不進行百分比編碼。但是，其他規範可以定義特殊含義，要求在這些額外特殊含義之外的字元進行百分比編碼。

form-urlencoded 媒體類型為 = 和 & 定義了特殊含義作為分隔符，並將 + 作為空格字元的替代（而不是其百分比編碼形式 %20）。這表示，雖然根據 RFC3986，這三個字元在查詢字串中是被保留但允許的，但在 form-urlencoded 查詢字串中，除非用於其 form-urlencoded 用途，否則必須進行百分比編碼；有關在表單值中處理 + 的範例，請參閱附錄 C。

百分比編碼和 form-data

RFC7578 建議使用基於 RFC3986 的百分比編碼作為一種機制，以將基於文字的每部分標頭資料（例如檔案名稱）保留在 ASCII 字元集中。此建議不屬於較舊（2015 年之前）的 form-data 規範的一部分，因此必須注意確保互通性。

form-data 媒體類型允許在其部分中使用任意文字或二進位資料，因此不需要百分比編碼，並且除非該部分的 Content-Type 被定義為需要百分比編碼，否則可能會導致互通性問題。

產生和驗證 URI 和 form-urlencoded 字串

URI 百分比編碼和 form-urlencoded 媒體類型具有複雜的規範歷史，跨越多個修訂版，並且在某些情況下，不同的標準機構聲稱擁有所有權。不幸的是，這些規範各自定義了稍微不同的百分比編碼規則，如果 URI 或 form-urlencoded 訊息主體將受到嚴格驗證，則需要考慮這些規則。（請注意，許多 URI 解析器預設不執行驗證。）

本規範規範性地引用以下相關標準

規範	日期	OAS 用法	百分比編碼	註解
RFC3986	01/2005	URI/URL 語法	[[RFC3986]]	取代 [[RFC1738]], [[RFC2396]]
RFC6570	03/2012	基於樣式的序列化	[[RFC3986]]	不使用 + 於 form‑urlencoded
RFC1866	11/1995	基於內容的序列化	[[RFC1738]]	已被 [[HTML401]] 第 17.13.4.1 節、[[URL]] 第 5 節取代

當存在 schema 時，參數物件中使用基於樣式的序列化，當至少存在 style、explode 或 allowReserved 其中之一時，編碼物件中使用基於樣式的序列化。有關 RFC6570 兩種不同百分比編碼方法的更多詳細資訊，包括涉及 + 的範例，請參閱附錄 C。

基於內容的序列化由媒體類型物件定義，並且在存在 content 欄位時，與參數物件一起使用，並在 style、explode 和 allowReserved 欄位不存在時，根據 contentType 欄位與編碼物件一起使用。每個部分都基於媒體類型（例如 text/plain 或 application/json）進行編碼，然後必須進行百分比編碼以用於 form-urlencoded 字串中。

請注意，form-data 的基於內容的序列化不期望或要求資料中進行百分比編碼，僅在每部分標頭值中需要。

與歷史規範的互通性

在大多數情況下，嚴格按照 [[RFC3986]] 產生查詢字串足以通過驗證（包括 JSON Schema 的 format: "uri" 和 format: "uri-reference"），但某些 form-urlencoded 實作仍然期望使用稍微嚴格的 [[RFC1738]] 規則。

由於所有符合 RFC1738 的 URI 都符合 RFC3986，因此需要確保歷史互通性的應用程式應使用 RFC1738 的規則。

與 Web 瀏覽器環境的互通性

WHATWG 是一個面向 Web 瀏覽器的標準組織，它定義了一個「URL Living Standard」，用於在瀏覽器上下文中解析和序列化 URL，包括解析和序列化 form-urlencoded 資料。WHATWG 對於查詢字串的百分比編碼規則是不同的，取決於查詢字串是被視為 form-urlencoded（其中它比 [[RFC1738]] 需要更多的百分比編碼）還是作為通用語法的一部分，其中它允許 [[RFC3986]] 禁止的字元。

需要與 Web 瀏覽器最大相容性的實作應該使用 WHATWG 的 form-urlencoded 百分比編碼規則。但是，它們不應該依賴 WHATWG 較寬鬆的通用查詢字串規則，因為產生的 URL 將無法通過 RFC3986 驗證，包括 JSON Schema 的 format: uri 和 format: uri-reference。

解碼 URI 和 form-urlencoded 字串

百分比解碼演算法不關心哪些字元進行了或未進行百分比解碼，這表示根據任何規範進行百分比編碼的 URI 都會被正確解碼。

同樣，所有 form-urlencoded 解碼演算法只是將 + 作為空格的處理新增到百分比解碼演算法中，並且無論使用哪種編碼規範，都將正常工作。

但是，如果 + 代表空格，則必須注意使用 form-urlencoded 解碼，如果 + 代表其自身作為文字值，則必須使用常規百分比解碼。

百分比編碼和非法或保留的分隔符

分別用作 deepObject、pipeDelimited 和 spaceDelimited 樣式的分隔符的 [、]、| 和空格字元，都必須進行百分比編碼以符合 [[RFC3986]]。這需要使用者以其他方式預先編碼參數名稱和值中的字元，以便在使用這些樣式之一時將其與分隔符用法區分開來。

空格字元始終是非法的，並且會被所有相關標準的所有版本的實作以某種方式編碼。雖然可以使用 form-urlencoded 的 + 約定來區分參數名稱和值中的空格與編碼為 %20 的 spaceDelimited 分隔符，但規範將解碼定義為單次通過，因此無法區分解碼結果中不同的用法。

某些環境在查詢字串中使用未編碼的 [、]，以及可能的 |，而沒有明顯的困難，並且 WHATWG 的通用查詢字串規則不要求對它們進行百分比編碼。如果程式碼依賴於保持這些分隔符未編碼，同時在名稱和值中使用常規百分比編碼，則無法保證在所有實作中都具有互通性。

為了獲得最大的互通性，建議在對這些樣式的分隔符進行百分比編碼時，定義並記錄額外的轉義約定，或完全避免使用這些樣式。附加編碼/轉義的確切方法留給 API 設計人員，並期望在執行本規範中描述的序列化和編碼之前執行，並在本規範的編碼和序列化步驟被反轉之後執行。這使其保持在本規範所管轄的流程之外。

附錄 F：解析參考文件中安全要求

本附錄說明如何檢索可透過 HTTP 存取的多文件 OpenAPI 描述 (OAD)，並解析參考（非進入點）文件中的安全要求物件。有關更多資訊，請參閱解析隱式連線。

首先，進入點文件是開始解析的地方。它定義了 MySecurity 安全方案為基於 JWT 的，並且定義了路徑項目作為另一個文件中組件的參考

GET /api/description/openapi HTTP/1.1
Host: www.example.com
Accept: application/openapi+json

"components": {
  "securitySchemes": {
    "MySecurity": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
},
"paths": {
  "/foo": {
    "$ref": "other#/components/pathItems/Foo"
  }
}

GET /api/description/openapi HTTP/1.1
Host: www.example.com
Accept: application/openapi+yaml

components:
  securitySchemes:
    MySecurity:
      type: http
      scheme: bearer
      bearerFormat: JWT
paths:
  /foo:
    $ref: 'other#/components/pathItems/Foo'

此進入點文件引用另一個沒有使用檔案副檔名的文件 other。這使客戶端可以靈活地基於每個資源選擇可接受的格式，假設這兩種表示形式都可用

GET /api/description/other HTTP/1.1
Host: www.example.com
Accept: application/openapi+json

"components": {
  "securitySchemes": {
    "MySecurity": {
      "type": "http",
      "scheme": "basic"
    }
  },
  "pathItems": {
    "Foo": {
      "get": {
        "security": [
          "MySecurity": []
        ]
      }
    }
  }
}

GET /api/description/other HTTP/1.1
Host: www.example.com
Accept: application/openapi+yaml

components:
  securitySchemes:
    MySecurity:
      type: http
      scheme: basic
  pathItems:
    Foo:
      get:
        security:
          - MySecurity: []

在 other 文件中，被參考的路徑項目具有針對安全方案 MySecurity 的安全要求。相同的安全方案存在於原始的進入點文件中。如解析隱式連線中所概述，MySecurity 使用實作定義的行為進行解析。但是，在該節中記錄，建議工具從進入點文件解析組件名稱。與所有實作定義的行為一樣，檢查工具文件以確定支援哪種行為非常重要。