# OpenAPI Specification 3.0 支持

使用 API 契约基于 OpenAPI 规范 (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-CN/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/all_of.png)
* 多态 (oneOf/anyOf) 允许您创建可以使用不同数据类型的属性的实体。
  * oneOf 允许您定义包含所选类型之一的属性的数据类型。例如，如果您创建了一个用于获取服务帐户信息的操作，则可以使用 oneOf 组合来定义响应，从而获取 Error 的所有属性或 ServiceAccountCount 的所有属性。![多态示例。](https://help.qlik.com/zh-CN/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-CN/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-CN/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-CN/cloud-services/Subsystems/Hub/Content/Resources/Images/ApiDesigner/designer_restrictions.png)