OpenAPI 規格 3.0 支援

上次更新：2026/10/20

使用 API 合約搭配 OpenAPI Specification (OAS) 3.0 設計 API。

OpenAPI 規格 3.0 推出了新功能，為 API 設計人員帶來更高的表達能力與生產力。

如需有關 OpenAPI 的詳細資訊，請參閱 Swagger 說明文件。

元件

元件可讓您在整個 API 中重複使用各種元素。這些元素可以是：

組合可讓您透過結合數個其他資料類型來建立新的資料類型。API 合約支援兩種組合類型：

組合 (allOf) 可讓您彙總來自不同結構描述的結構描述屬性。例如，您可以透過重複使用現有類型 Contact 和 Error 的所有屬性，來定義資料類型 Company。
多型 (oneOf/anyOf) 可讓您建立能夠使用不同資料類型屬性的實體。
- oneOf 可讓您定義包含其中一個所選類型之屬性的資料類型。例如，如果您建立取得服務帳戶資訊的作業，可以使用 oneOf 組合來定義回應，以取得 Error 的所有屬性或 ServiceAccountCount 的所有屬性。
- anyOf 可讓您定義包含一或多個所選類型屬性的資料類型。例如，您可以定義包含不同屬性的資料類型 nervousSystem 和類型 skeleton，並使用 anyOf 組合來建立包含這兩種類型中任一者之任何屬性的資料類型。
  只要 anyOf 組合包含所選資料類型中至少一種的所有必要參數，即為有效。以下範例使用來自 nervousSystem 類型的 brain_weight 屬性，以及來自 skeleton 的 skull_height 和 teeth 屬性。