OpenAPI Specification 3.0 支持

上次更新日期：2026/10/20

使用 API 契约基于 OpenAPI 规范 (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 属性。