此页面由 Cloud Translation API 翻译。

OpenAPI 3.x 功能限制

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

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

新的 OpenAPI 3.x 限制

本部分介绍了 OpenAPI 3.x 中新增的功能的限制。

OpenAPI 3.x 支持多个 server 对象来定义主机和基本路径。不过，API Gateway 依赖于由 x-google-endpoint 扩展程序标识的单个服务器对象来配置服务。

虽然您可以定义多个服务器，但 API 网关仅考虑包含 x-google-endpoint 扩展程序的服务器，并且只允许一个此类服务器。对于 API Gateway，不需要服务器网址，因此您可以不定义任何服务器，也可以定义一个带有 x-google-endpoint 扩展程序的服务器。

例如，以下定义对于 API Gateway 有效：

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

以下定义是无效的，因为它包含多个 x-google-endpoint 扩展程序：

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

以下定义对 API Gateway 有效，但 API Gateway 会忽略服务器对象：

servers:
  - url: https://example.com

如果您上传了多个 OpenAPI 文件，并且其中一个文件包含具有 x-google-endpoint 扩展名的服务器，那么所有文件还必须包含具有相同 x-google-endpoint 扩展名和相同服务器网址主机名的服务器定义。不同文件之间的基本路径可能不同。

对于 API Gateway，servers 对象中的相对网址会被视为单独的基本路径，因为规范中不需要主机名。这与标准 OpenAPI 行为不同，后者会根据托管 OpenAPI 定义的服务器解析相对网址。例如，API 网关会将 url: /v1 视为基本路径。

基本路径必须以“/”开头。API 网关会拒绝没有方案或以“/”开头的网址，因为这些网址表示的是基本路径。

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

API 网关对上传的 OpenAPI 3.x 文件强制执行 10MB 的总大小限制和 50 的文件数量限制。

本部分介绍了从 OpenAPI 2.0 沿用至今的限制，这些限制也适用于 OpenAPI 3.x。

虽然 API Gateway 接受已在安全方案对象内定义了范围的 OpenAPI 文档，但 API Gateway 不会检查或强制执行这些范围。

API 密钥要求：如果其中一个方案是 API 密钥，API 网关不支持替代（逻辑 OR）安全性要求。不过，API Gateway 支持合取（逻辑 AND），因此您可以同时要求提供 API 密钥和 OAuth2 令牌。
OAuth2 要求：API 网关支持针对不同 OAuth2 安全方案的替代（逻辑 OR）安全性要求。除非额外的安全要求是 API 密钥，否则 API Gateway 不支持合取（逻辑 AND）。
可选安全性：您可以使用空的安全要求 (- {}) 将 API 密钥的安全性设为可选，但 API 网关不支持 OAuth 的此功能。

如果 OpenAPI 3.x 规范使用的安全要求在 securityDefinitions 部分中没有对应的定义，API Gateway 将拒绝该规范。

API Gateway 仅支持表示整个路径段的网址路径模板参数，例如 /items/{itemId}。API Gateway 不支持与部分片段对应的参数，例如 /items/prefix_{id}_suffix，并且会拒绝此类参数。

API Gateway 接受包含各种参数和类型定义（例如 required 参数和数组格式）的 OpenAPI 文档，但不会强制执行这些定义。无论这些定义如何，API Gateway 都会将传入的请求转发到您的 API。

API 网关仅支持请求参数中的基元类型。

API 网关不支持对所提供的 OpenAPI 文档外部的类型的引用。例如，API Gateway 不允许指向外部网址的 $ref，并会拒绝此类 $ref。

API Gateway 不允许在 OpenAPI 文档的 servers.url 字段中使用自定义端口。

提交给 API Gateway 的 OpenAPI 文档最多可以包含 200 个 YAML 别名节点。