本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# OpenAPI 架构目标
<a name="gateway-schema-openapi"></a>

OpenAPI（以前称为 Swagger）是描述 RESTful API 的广泛使用的标准。Gateway 支持用于定义 API 目标的 OpenAPI 3.0 规范。

OpenAPI 目标将您的网关连接到使用 OpenAPI 规范定义的 REST API。网关将传入的 MCP 请求转换为对这些 API 的 HTTP 请求，并处理响应格式。

查看关键注意事项和限制，包括功能支持，以帮助您决定 OpenAPI 目标是否适用于您的用例。如果是，则可以创建符合规范的架构，然后为网关设置访问目标的权限。选择一个主题以了解更多信息：

**Topics**
+ [主要注意事项和局限性](#gateway-schema-openapi-considerations)
+ [授权策略](#gateway-openapi-auth-strategy)
+ [OpenAPI 架构规范](#gateway-openapi-schema)

## 主要注意事项和局限性
<a name="gateway-schema-openapi-considerations"></a>

**重要**  
OpenAPI 规范必须包含您要作为工具公开的所有操作的`operationId`字段。在 MCP 界面中，操作 ID 用作工具名称。

使用 OpenAPI 目标时，请记住以下要求和限制：
+ 支持 OpenAPI 版本 3.0 和 3.1（不支持 Swagger 2.0）
+ OpenAPI 文件必须没有语义错误
+ 服务器属性需要有实际端点的有效 URL
+ 仅完全支持 application/json 内容类型
+ 不支持 oneOf、AnyOf 和 allOf 等复杂架构功能
+ 不支持用于查询、标头和 cookie 参数的路径参数序列化器和参数序列化器
+ 每个 LLM 都有约 ToolSpec 束条件。如果 OpenAPI 的 APIs/properties/object 名称不符合相应 ToolSpec 的下游 LLM，则数据平面将出现故障。常见错误是属性名称超过允许的长度或名称包含不支持的字符。

为了实现 OpenAPI 目标的最佳结果：
+ 在所有操作中始终包含 operationID
+ 使用简单的参数结构代替复杂的序列化
+ 在规范之外实施身份验证和授权
+ 仅使用支持的媒体类型以实现最大兼容性

### URL 参数的安全最佳实践
<a name="gateway-openapi-url-security"></a>

**警告**  
在您的 OpenAPI 规范中定义服务器 URL 时，请避免使用过于宽松的 URL 参数模式，这可能会使您的网关面临安全风险。

OpenAPI 服务器定义中的 URL 参数允许动态端点配置。但是，如果限制不当，某些模式可能会带来安全漏洞。具体而言，请避免使用完全动态的域模式，例如：
+  `https://{yourDomain}/`-允许任意域替换
+  `https://{subdomain}.{env}.{domain}.com`-多个不受限制的占位符
+  `https://{host}/api/`-不受限制的主机参数

这些模式可能会被利用来：
+ 将请求重定向到意外或恶意端点
+ 访问内部网络资源（Server-Side 请求伪造）
+ 泄露凭据或敏感数据

 **推荐做法：**
+ 尽可能使用完全限定的静态 URL：`https://api.example.com/v1`
+ 将参数限制在您的控制域中的子域中，并在您的应用程序中实现验证
+ 避免使用允许任意域或主机替换的参数
+ 在您的 API 中实现额外的验证，以验证运行时参数值是否与预期模式相匹配

AgentCore 网关会自动验证区域参数并阻止对私有 IP 范围的请求。

安全服务器 URL 配置示例：

```
{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}
```

如果需要动态参数，请使用占位符和枚举限制最低的完全限定域：

```
{
  "servers": [
    {
      "url": "https://{tenant}.api.example.com/v1",
      "variables": {
        "tenant": {
          "default": "default-tenant",
          "description": "Customer tenant identifier",
          "enum": ["tenant1", "tenant2", "tenant3"]
        }
      }
    }
  ]
}
```

这种方法将 URL 参数限制为受控域中的特定子域，同时保持多租户部署的灵活性。使用枚举限制可以防止任意值，并通过将参数限制为预定义的安全值来帮助防御 SSRF 攻击。此外，请务必在应用程序逻辑中验证租户值。

在考虑将 OpenAPI 架构目标与 AgentCore 网关一起使用时，请查看以下功能支持表。

### OpenAPI 功能支持
<a name="gateway-schema-openapi-features"></a>

下表概述了网关支持和不支持的 OpenAPI 功能：


| 支持的功能 | 不支持的特征 | 
| --- | --- | 
|  **架构定义**基本数据类型（字符串、数字、整数、布尔值、数组、对象）必填字段验证嵌套对象结构带有项目规格的数组定义 |  **架构组合 ** oneOf 规范 AnyOF 规格所有规范 | 
|  **HTTP 方法**标准 HTTP 方法（GET、POST、PUT、DELETE、PATCH、HEAD、选项） |  ****安全方案 OpenAPI 规范级别的安全方案（必须使用网关的出站授权配置进行身份验证） | 
|  **媒体类型 ** application/json application/xml multipart/form-数据-www-form-urlencoded application/x |  **媒体类型支持列表之外的**自定义媒体类型二进制媒体类型 | 
|  **路径参数**简单路径参数定义（示例：/users/ {userId}） |  **参数序列化**复杂路径参数序列化器（示例：`/users { ;id\*} { ?metadata}`）具有复杂序列化的查询参数数组标头参数序列化器 Cookie 参数序列化器 | 
|  **查询参数**基本查询参数定义简单字符串、数字和布尔类型 |  **回调和 Webhook ** 回调操作 Webhook 定义 | 
|  **Request/Response 正文 ** JSON 请求和响应正文 XML 请求和响应正文标准 HTTP 状态码（200、201、400、404、500 等） |  ****链接操作间的链接 | 

## 授权策略
<a name="gateway-openapi-auth-strategy"></a>

OpenAPI 目标支持以下类型的出站授权：
+ 没有授权-网关在没有预先配置的授权的情况下调用 OpenAPI 目标。不建议使用这种方法。
+ OAuth — 网关支持两段式 OAuth（客户端凭证授予类型）和三段 OAuth（授权码授权类型）。您可以在 Amazon Bedrock AgentCore Identity 中将授权提供商配置为与网关相同的账户和区域。
+ API 密钥 — 网关使用 API 密钥凭据提供商向 OpenAPI 目标进行身份验证。您在与网关相同的账户和区域中配置 Amazon Bedrock I AgentCore dentity 中的 API 密钥提供商。
+ IAM（[Amazon 签名版本 4 (Sig V4)](https://docs.amazonaws.cn/AmazonS3/latest/API/sig-v4-authenticating-requests.html)）— 网关使用带有网关服务角色证书的 SigV4 对 OpenAPI 目标的请求进行签名。您可以`IamCredentialProvider`使用 SigV4 签名所需的服务名称和可选区域（默认为网关区域）来配置。

**重要**  
IAM (SigV4) 出站授权要求 OpenAPI 目标托管在原生支持 IAM 身份验证的 Amazon 服务后面。网关使用 SigV4 签署出站请求，但不修改目标上的身份验证配置。目标服务必须能够验证 SigV4 签名。  
以下 Amazon 服务本身支持 IAM 身份验证，并且与 OpenAPI 目标的 IAM 出站授权兼容：  
Amazon API Gateway
Lambda 函数 URL
亚马逊基岩网关 AgentCore 
不进行本地验证 SigV4 签名的服务，例如应用程序负载均衡器或直接 Amazon EC2 终端节点，与 IAM 出站授权不兼容。如果您的 OpenAPI 目标托管在其中一项服务之后，请改用 OAuth 或 API 密钥授权。

有关设置出站授权的更多信息，请参阅为网关[设置出站授权](gateway-outbound-auth.md)。

## OpenAPI 架构规范
<a name="gateway-openapi-schema"></a>

OpenAPI 规范定义了您的网关将公开的 REST API。设置 OpenAPI 规范时，请参阅以下资源：
+ 有关 OpenAPI 规范格式的信息，请参阅 Op [ enAPI 规范。](https://swagger.io/specification/)
+ 有关在 AgentCore 网关中使用 OpenAPI 规范时支持和不支持的功能的信息，请参阅 O [ penAPI 功能支持中的表格。](#gateway-schema-openapi-features)遵守这些要求以防止在创建和调用目标时出错。

定义 OpenAPI 架构后，您可以执行以下操作之一：
+ 将其上传到 Amazon S3 存储桶，并在将目标添加到网关时参考 S3 位置。
+ 将目标添加到网关时，将定义粘贴到内联中。

展开一节，查看支持和不支持的 OpenAPI 规范示例：

### 支持的 OpenAPI 规范示例 1
<a name="w2aac24c18c13c15c13b1"></a>

以下显示了支持的 OpenAPI 规范的示例

支持的 OpenAPI 规范示例：

```
{
  "openapi": "3.0.0",
  "info": {
    "title": "Weather API",
    "version": "1.0.0",
    "description": "API for retrieving weather information"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/weather": {
      "get": {
        "summary": "Get current weather",
        "description": "Returns current weather information for a location",
        "operationId": "getCurrentWeather",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "description": "City name or coordinates",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "units",
            "in": "query",
            "description": "Units of measurement (metric or imperial)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["metric", "imperial"],
              "default": "metric"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": "string"
                    },
                    "temperature": {
                      "type": "number"
                    },
                    "conditions": {
                      "type": "string"
                    },
                    "humidity": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "404": {
            "description": "Location not found"
          }
        }
      }
    }
  }
}
```

### 支持的 OpenAPI 规范示例 2
<a name="w2aac24c18c13c15c13b3"></a>

以下是支持的 OpenAPI 规范的另一个示例。

```
{
  "openapi": "3.0.0",
  "info": {
    "title": "Search API",
    "version": "1.0.0",
    "description": "API for searching content"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "summary": "Search for content",
        "operationId": "searchContent",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "Search query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "snippet": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    }
  }
}
```

### 不支持的 OpenAPI 架构
<a name="w2aac24c18c13c15c13b5"></a>

以下显示了 oneOf 不支持的架构的示例：

```
{
  "oneOf": [
    {"$ref": "#/components/schemas/Pencil"},
    {"$ref": "#/components/schemas/Pen"}
  ]
}
```