OpenAPI 3.x 功能限制

本文档介绍了将 OpenAPI 3.x 与 Endpoints 搭配使用时的功能限制。

如需详细了解支持的 OpenAPI 规范版本，请参阅 OpenAPI 概览。

新的 OpenAPI 3.x 限制

本部分介绍了 OpenAPI 3.x 支持新增的 OpenAPI 限制。

服务器

OpenAPI 3.x 支持多个 server 对象来定义主机和基本路径。不过，Cloud Endpoints 仅使用单个服务器对象来配置主机名和基本路径，该对象由 x-google-endpoint 扩展标识。

虽然您可以在 OpenAPI 规范中定义多个服务器，但 Cloud Endpoints 仅使用具有 x-google-endpoint 扩展程序的服务器。您只能在一个服务器上定义 x-google-endpoint 扩展程序。

对于 Cloud Endpoints，必须提供主机名，因此只能有一个服务器具有 x-google-endpoint 扩展程序。

例如，以下服务器定义对于 Cloud Endpoints 是有效的：

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}
  - url: https://example.com

以下服务器定义对于 Endpoints 是无效的：

servers:
  - url: https://my-api-1.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}
  - url: https://my-api-2.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}

以下定义也对 Cloud Endpoints 无效：

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog

多个文件中的服务器

如果您上传多个 OpenAPI 文件，所有文件都必须遵守 servers 部分的限制。如果一个文件包含扩展名为 x-google-endpoint 的服务器，则所有文件都必须定义扩展名为 x-google-endpoint 的服务器。

此外，所有扩展名为 x-google-endpoint 的服务器都必须在服务器网址中使用相同的主机，并且所有文件中的 x-google-endpoint 配置必须完全相同。服务器网址中的基本路径可能有所不同。

相对网址

Cloud Endpoints 需要主机名，因此不支持相对网址。

不受支持的扩展程序

OpenAPI 3.x 不支持 x-google-allow 扩展程序。

现有限制

本部分介绍了 OpenAPI 2.0 中存在的限制，这些限制仍然适用于 OpenAPI 3.x。

范围被忽略

虽然您可以在安全方案对象中定义范围，但 ESP 或 Cloud Endpoints Frameworks 不会检查这些范围。

多个安全性要求

您可以在 OpenAPI 文档中指定多个安全性要求。

  • 包含 API 密钥的安全性要求：当其中一个方案是 API 密钥时，Cloud Endpoints 不支持替代（逻辑 OR）安全性要求。Cloud Endpoints 支持合取（逻辑 AND），因此您可以同时要求 API 密钥和 OAuth2 身份验证。

  • OAuth2 的安全性要求：Cloud Endpoints 支持针对不同 OAuth2 身份验证方案的替代（逻辑 OR）安全性要求。除非额外的安全要求是 API 密钥，否则 Cloud Endpoints 不支持合取（逻辑 AND）。

  • 可选安全性要求：OpenAPI 3 支持通过包含空要求 ({}) 来实现可选安全性。API 密钥支持此功能，但 OAuth 不支持。

安全定义验证

对于 OpenAPI 3.x，使用未定义的安全架构会导致错误，并且 Cloud Endpoints 会拒绝该规范。这与 OpenAPI 2.0 不同，在 OpenAPI 2.0 中，此情况只会产生警告。

网址路径模板

Cloud Endpoints 仅支持与整个路径段（由 / 分隔）对应的网址路径模板参数。Cloud Endpoints 不支持与部分路径段对应的参数。

例如，Cloud Endpoints 支持 /items/{itemId}，但不支持 /items/overview.{format}。

针对网址根路径 / 的操作

虽然 OpenAPI 文档接受针对根路径 / 的操作，但 Extensible Service Proxy 拒绝针对根路径的请求。此限制不适用于支持根路径的 ESPv2。

参数、架构、请求正文和类型

Extensible Service Proxy 和 ESP 会忽略大多数参数、架构、请求正文和类型定义。Extensible Service Proxy 和 ESP 不强制执行必需参数和类型定义，而是将请求转发到您的 API。

Extensible Service Proxy 和 ESP 仅支持请求参数中的基本类型。

外部类型引用

Cloud Endpoints 不支持对 OpenAPI 文档外部的类型的引用。例如，您不能使用指向外部网址的 $ref。

服务主机地址中的自定义端口

您无法在 servers 对象的 url 中使用自定义端口。

YAML 别名限制

一个 OpenAPI 文档最多可以包含 200 个 YAML 别名节点。

非重复请求正文

每个操作只能定义一个 requestBody，且该 requestBody 必须为非重复类型。