Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

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 Gateway 仅考虑包含 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 Gateway 会将 url: /v1 视为基本路径。

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

不受支持的扩展程序

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

文件大小限制

API Gateway 对上传的 OpenAPI 3.x 文件设置了 10MB 的总大小限制和 50 个的文件数量限制。

MCP 限制

在公开预览版期间，Model Context Protocol (MCP) 支持存在以下限制：

工具数量限制：每个网关的 MCP 工具数量上限为 1,000 个。
HTTP 方法：只有 GET、POST、PUT、PATCH 和 DELETE 操作可以作为 MCP 工具公开。不支持 HEAD、OPTIONS 和 TRACE。
流式传输：不支持长时间运行的工具调用的服务器发送事件 (SSE) 流式传输。
批量请求：JSON-RPC 批处理数组会被拒绝。
多模态载荷：工具响应仅限于 UTF-8 文本。不支持二进制响应。
无状态性：实现是无状态的；不使用或维护会话标识符（例如 MCP-Session-Id）。
不支持的 MCP 方法：不支持 resources/*、prompts/*、sampling/*、completion/*、ping 和 logging/* 等专用方法，并且会返回 JSON-RPC 错误代码 -32601。
身份验证限制：tools/list 方法仅支持 JWT 身份验证。此方法不支持 API 密钥身份验证。
无工具注释：工具声明中不会发出 destructiveHint 或 readOnlyHint 等提示。
CORS 预检：网关不会管理 /mcp 路径上的自动 CORS 预检处理（OPTIONS 请求）。
模型路由互斥：您无法在同一 API 配置中同时使用 MCP 和模型路由。
不支持的 MCP 响应：不支持在响应中返回空正文的操作，例如 HTTP 204 响应。
架构发现：由于存在已知的配置处理限制，从 OpenAPI 规范派生的复杂嵌套对象架构可能无法在 tools/list 发现响应中完全或正确呈现。

现有限制

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

范围被忽略

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

多个安全性要求

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

外部类型引用

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

主机地址中的自定义端口

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

YAML 别名限制

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