OpenAPI 結構描述目標

OpenAPI （先前稱為 Swagger) 是描述 RESTful APIs的廣泛使用標準。Gateway 支援定義 API 目標的 OpenAPI 3.0 規格。

OpenAPI 目標會將閘道連線至使用 OpenAPI 規格定義的 REST APIs。Gateway 會將傳入的 MCP 請求轉換為這些 APIs HTTP 請求，並處理回應格式。

檢閱關鍵考量事項和限制，包括功能支援，以協助您決定 OpenAPI 目標是否適用於您的使用案例。如果是，您可以建立遵循規格的結構描述，然後設定閘道的許可以存取目標。選取主題以進一步了解：

主題

重要考量和限制
授權策略
OpenAPI 結構描述規格

重要考量和限制

重要

OpenAPI 規格必須包含要公開為工具之所有操作operationId的欄位。operationId 用作 MCP 界面中的工具名稱。

使用 OpenAPI 目標時，請記住下列要求和限制：

支援 OpenAPI 3.0 和 3.1 版（不支援 Swagger 2.0)
OpenAPI 檔案必須沒有語意錯誤
伺服器屬性需要實際端點的有效 URL
僅完全支援應用程式/json 內容類型
不支援複雜的結構描述功能，例如 oneOf、anyOf 和 allOf
不支援查詢、標頭和 Cookie 參數的路徑參數序列化程式和參數序列化程式
每個 LLM 都有 ToolSpec 限制。如果 OpenAPI APIs/properties/object名稱不符合個別下游 LLMs 的工具ToolSpec，則資料平面將會失敗。常見錯誤是超過允許長度的屬性名稱，或包含不支援字元的名稱。

若要取得 OpenAPI 目標的最佳結果：

一律在所有操作中包含 operationId
使用簡單的參數結構，而非複雜的序列化
在規格之外實作身分驗證和授權
僅使用支援的媒體類型以獲得最大的相容性

URL 參數的安全最佳實務

警告

在 OpenAPI 規格中定義伺服器 URLs 時，請避免使用過於寬鬆的 URL 參數模式，這些模式可能會讓您的閘道面臨安全風險。

OpenAPI 伺服器定義中的 URL 參數允許動態端點組態。不過，如果沒有適當限制，某些模式可能會引入安全漏洞。具體而言，避免使用完全動態的網域模式，例如：

https://{yourDomain}/ - 允許任意網域替換
https://{subdomain}.{env}.{domain}.com - 多個不受限制的預留位置
https://{host}/api/ - 不受限制的主機參數

可能會利用這些模式來：

將請求重新導向至非預期或惡意端點
存取內部網路資源（伺服器端請求偽造）
滲透登入資料或敏感資料

建議實務：

盡可能使用完全合格的靜態 URLs： https://api.example.com/v1
將參數限制為受控網域內的子網域，並在應用程式中實作驗證
避免使用允許任意網域或主機替換的參數
在 API 中實作其他驗證，以確認執行時間參數值符合預期的模式

AgentCore Gateway 會自動驗證區域參數，並封鎖對私有 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 攻擊。此外，請一律驗證應用程式邏輯中的租戶值。

在考慮搭配 AgentCore Gateway 使用 OpenAPI 結構描述目標時，請檢閱下列功能支援資料表。

OpenAPI 功能支援

下表概述 Gateway 支援和不支援的 OpenAPI 功能：

支援的功能	不支援的功能
結構描述定義基本資料類型（字串、數字、整數、布林值、陣列、物件）必要欄位驗證巢狀物件結構陣列定義與項目規格	結構描述合成 oneOf 規格 anyOf 規格 allOf 規格
HTTP 方法標準 HTTP 方法 (GET、POST、PUT、DELETE、PATCH、HEAD、OPONS)	安全結構描述 OpenAPI 規格層級的安全結構描述（必須使用閘道的傳出授權組態來設定身分驗證）
媒體類型應用程式/json application/xml multipart/form-data application/x-www-form-urlencoded	媒體類型超出支援清單的自訂媒體類型二進位媒體類型
路徑參數簡易路徑參數定義（範例：/users/ { userId})	參數序列化複雜路徑參數序列化程式（範例：`/users { ;id\*} { ?metadata}`) 查詢具有複雜序列化標頭參數序列化程式 Cookie 參數序列化程式的參數陣列
Query Parameters Basic 查詢參數定義簡單字串、數字和布林值類型	回呼和 Webhooks 回呼操作 Webhook 定義
請求/回應主體 JSON 請求和回應主體 XML 請求和回應主體標準 HTTP 狀態碼 (200、201、400、404、500 等）	連結操作之間的連結

授權策略

OpenAPI 目標支援以下類型的傳出授權：

無授權 – 閘道在沒有預先設定的授權的情況下叫用 OpenAPI 目標。不建議使用此方法。
OAuth – 閘道支援兩邊 OAuth （用戶端登入資料授予類型）和三邊 OAuth （授權碼授予類型）。您可以在與閘道相同的帳戶和區域中，在 Amazon Bedrock AgentCore Identity 中設定授權提供者。
API 金鑰 – 閘道使用 API 金鑰登入資料提供者來驗證 OpenAPI 目標。您可以在與閘道位於相同帳戶和區域中的 Amazon Bedrock AgentCore Identity 中設定 API 金鑰提供者。
IAM ( AWS Signature 第 4 版 (Sig V4)) – 閘道使用 SigV4 搭配閘道服務角色憑證來簽署 OpenAPI 目標的請求。您可以使用 SigV4 簽署IamCredentialProvider所需的服務名稱和選用區域（預設為閘道區域）來設定。

重要

IAM (SigV4) 傳出授權要求 OpenAPI 目標託管在原生支援 IAM 身分驗證 AWS 的服務後方。閘道會使用 SigV4 簽署傳出請求，但不會修改目標上的身分驗證組態。目標服務必須能夠驗證 SigV4 簽章。

下列 AWS 服務原生支援 IAM 身分驗證，並與 OpenAPI 目標的 IAM 傳出授權相容：

Amazon API Gateway
Lambda 函數 URLs
Amazon Bedrock AgentCore Gateway

原生不會驗證 SigV4 簽章的服務，例如 Application Load Balancer 或直接 Amazon EC2 端點，與 IAM 傳出授權不相容。如果您的 OpenAPI 目標託管在這些服務的後面，請改用 OAuth 或 API 金鑰授權。

如需設定傳出授權的詳細資訊，請參閱設定閘道的傳出授權。

OpenAPI 結構描述規格

OpenAPI 規格會定義閘道將公開的 REST API。設定 OpenAPI 規格時，請參閱下列資源：

如需 OpenAPI 規格格式的相關資訊，請參閱 OpenAPI 規格。
如需有關搭配 AgentCore Gateway 使用 OpenAPI 規格時支援和不支援的功能的資訊，請參閱 OpenAPI 功能支援中的資料表。遵守這些要求，以防止在目標建立和調用期間發生錯誤。

定義 OpenAPI 結構描述之後，您可以執行下列其中一項操作：

將其上傳至 Amazon S3 儲存貯體，並在您將目標新增至閘道時參考 S3 位置。
當您將目標新增至閘道時，將定義內嵌貼上。

展開區段以查看支援和不支援 OpenAPI 規格的範例：

以下顯示支援的 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 規格範例。


{
  "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"
          }
        }
      }
    }
  }
}

以下顯示使用 oneOf 的不支援結構描述範例：


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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

API Gateway 階段

Smithy 模型