# OpenAPI 規格 3.0 支援

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

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

如需有關 OpenAPI 的詳細資訊，請參閱 [Swagger 說明文件](https://swagger.io/docs/specification/about/)。

## 元件

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

* 路徑變數
* 查詢參數
* 標頭
* 回應

## 組合

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

* 組合 (allOf) 可讓您彙總來自不同結構描述的結構描述屬性。例如，您可以透過重複使用現有類型 Contact 和 Error 的所有屬性，來定義資料類型 Company。![組合的範例。](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/all_of.png)
* 多型 (oneOf/anyOf) 可讓您建立能夠使用不同資料類型屬性的實體。
  * oneOf 可讓您定義包含其中一個所選類型之屬性的資料類型。例如，如果您建立取得服務帳戶資訊的作業，可以使用 oneOf 組合來定義回應，以取得 Error 的所有屬性或 ServiceAccountCount 的所有屬性。![多型的範例。](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/oneof.png)

  * anyOf 可讓您定義包含一或多個所選類型屬性的資料類型。例如，您可以定義包含不同屬性的資料類型 nervousSystem 和類型 skeleton，並使用 anyOf 組合來建立包含這兩種類型中任一者之任何屬性的資料類型。

    只要 anyOf 組合包含所選資料類型中至少一種的所有必要參數，即為有效。以下範例使用來自 nervousSystem 類型的 brain\_weight 屬性，以及來自 skeleton 的 skull\_height 和 teeth 屬性。

    ![使用 nervousSystem 與 skeleton 資料類型的組合範例。](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/anyof.png)

如需關於組合與多型的詳細資訊，請參閱 [繼承與多型](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) 和 [anyOf 與 oneOf 的差異](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#anyof-vs-oneof)。

## 回應

OAS 3.0 允許您為您的作業定義新類型的回應：

* 回應範圍：與其定義像 200 這樣的回應，您可以將其設定為 2XX，使其包含從 200 到 299 的回應。
* 預設回應：您可以定義在未定義特定或範圍回應時 要傳回的預設回應。

以明確代碼定義的回應優先於回應範圍和預設回應，而回應範圍則優先於預設回應。在下列範例中：

* 204 回應已定義，且優先於其他回應。
* 2XX 回應適用於回應代碼 200 至 203 以及 205 至 299。
* 預設回應適用於所有 1XX、3XX、4XX 和 5XX 回應。

![回應區段。](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/responses-headers-api.png)

## 安全性

OAS 3.0 為您的 API 帶來了新的安全性配置：

* Bearer 驗證
* OpenIdConnect

## 限制

OAS 3.0 允許您指定某些屬性為唯讀或唯寫。

此選項僅適用於資料類型，且無法在作業層級的請求或回應中定義。

![限制範例。](https://help.qlik.com/zh-TW/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/designer_restrictions.png)