修改閘道以使用 OpenAPI 3.x

本頁說明如何修改現有 API 閘道，以便使用 OpenAPI 3.x 規格進行 API 設定。

事前準備

• 確認您已設定現有的 API Gateway 執行個體，並使用 OpenAPI 2.0 規格。
• 安裝 gcloud CLI。詳情請參閱「安裝 Google Cloud CLI」。

修改 API 設定，改用 OpenAPI 3.x

如要修改現有的 OpenAPI 2.0 API Gateway 設定，改用 OpenAPI 3.x，請完成下列步驟：

找出目前的 API 設定

找出與閘道相關聯的 API 設定。

1. 說明 API Gateway 執行個體：

   gcloud api-gateway gateways describe GATEWAY_ID --project=PROJECT_ID --location=GATEWAY_LOCATION
   

   更改下列內容：

   • GATEWAY_ID：閘道的 ID。
   • PROJECT_ID：您的 Google Cloud 專案 ID
   • GATEWAY_LOCATION：閘道位置。

   輸出內容會顯示 apiConfig 路徑，例如：

   apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-gateway-config
   createTime: '2025-03-25T02:49:58.641650649Z'
   defaultHostname: my-gateway-a1b2c3d4.uc.gateway.dev
   displayName: My gateway
   name: projects/my-project/locations/us-west1/gateways/my-new-gateway
   state: ACTIVE
   updateTime: '2025-03-25T02:51:52.674308428Z'
   

取得 OpenAPI 文件

如要取得您識別的 API 設定 OpenAPI 文件，請按照下列步驟操作：

1. 說明 API 設定：

   gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID --project=PROJECT_ID --view=FULL
   

   更改下列內容：

   • CONFIG_ID：API 設定的 ID。
   • API_ID：API 的 ID。
   • PROJECT_ID：您的 Google Cloud 專案 ID

   輸出內容會顯示 openapiDocuments 區段，其中包含 OpenAPI 文件的 base64 編碼內容：

   createTime: '2024-02-16T21:11:36.293169474Z'
   displayName: my-api-config
   gatewayServiceAccount: projects/-/serviceAccounts/[e-mail]
   name: projects/my-project-id/locations/global/apis/my-api/configs/my-gateway-config
   openapiDocuments:
   -   document:
       contents: IyBvc...
       path: apigateway-config.yaml
   serviceConfigId: my-api-config-0a1fjkfeb7t8z
   state: ACTIVE
   updateTime: '2024-02-16T21:13:45.626771120Z'
   

解碼 OpenAPI 文件

如要解碼以 base64 編碼的 OpenAPI 文件內容，請按照下列步驟操作：

1. 解碼 contents 值：

   echo 'IyBvc...' | base64 -d
   

   將 IyBvc... 替換為上一步的實際 contents 值。

   輸出內容會顯示 OpenAPI 2.0 文件，例如：

   swagger: '2.0'
   info:
     title: API_ID
     description: Sample API on API Gateway with a Google Cloud Functions backend
     version: 1.0.0
   

將 OpenAPI 文件轉換為 OpenAPI 3.x

您可以使用工具將 OpenAPI 2.0 文件轉換為 OpenAPI 3.x。舉例來說，Swagger 編輯器提供轉換公用程式。

初步轉換為 OpenAPI 3.x 後，請手動對文件套用任何其他變更，以符合 OpenAPI 3.x，並確保與 API Gateway 擴充功能和功能相容。如要進一步瞭解 API Gateway 支援的 OpenAPI 3.x 擴充功能，請參閱「API Gateway 中的 OpenAPI 3.x 擴充功能」。

下表說明必要變更：

功能	OpenAPI 2.0	OpenAPI 3.x	變更說明
API 金鑰	securityDefinitions	securitySchemes	API 金鑰使用現成的 OpenAPI API 金鑰支援功能。轉換工具通常會自動處理這項作業。無須手動變更。
JWT 驗證	x-google-audiences 等	x-google-auth	在 OpenAPI 2.0 擴充功能中，您可以使用 securityDefinition 執行個體上的個別擴充功能定義 OAuth 設定。轉換工具會將安全機制執行個體轉換為 #/components/securitySchemes，並保留擴充功能。手動修改這些擴充功能，使其成為 x-google-auth 的子項，並移除 x-google- 前置字元。值保持不變。
配額	x-google-management、x-google-quota	x-google-api-management、x-google-quota	在 OpenAPI 2.0 擴充功能中，您可以在 x-google-management 中定義指標和配額，並使用 x-google-quota 附加這些項目。轉換工具會保留這些擴充功能。手動將指標和配額設定從 x-google-management 移至 x-google-api-management。將設定變更為使用 YAML 鍵，並移除 valueType、metricKind 和 unit。從 x-google-quota 的執行個體中移除 metricCosts。
後端	x-google-backend	x-google-api-management、x-google-backend	在 OpenAPI 2.0 擴充功能中，您可以在 x-google-backend 中定義後端，而設定會套用至定義位置。在 OpenAPI 3.x 擴充功能中，您可以在 x-google-api-management 中定義後端，然後使用 x-google-backend 套用。轉換工具會保留這個擴充功能。手動將設定移至 x-google-api-management。修改 x-google-backend 的執行個體，以參照該設定。
端點	x-google-endpoints	x-google-endpoint、servers	在 OpenAPI 2.0 擴充功能中，您可以在 x-google-endpoints 中定義端點設定。在 OpenAPI 3.x 擴充功能中，您會使用 x-google-endpoint，但這是 servers 的擴充功能，而不是根層級的擴充功能。轉換工具會保留這個擴充功能。請手動將此項目移至 servers，並移除 name 欄位。例如： # OpenAPI 2.0 x-google-endpoints: - name: "my-api.apigateway.my-project.cloud.goog" allowCors: True # OpenAPI 3.0.x servers: - url: https://my-api.apigateway.my-project.cloud.goog/ x-google-endpoint: allowCors: True
API 名稱	x-google-api-name	x-google-api-management	在 OpenAPI 2.0 擴充功能中，您可以在 x-google-api-name 中定義 API 名稱。在 OpenAPI 3.x 擴充功能中，您可以使用 x-google-api-management 中的 apiName 欄位。手動將這項設定移至 x-google-api-management。
允許所有流量	x-google-allow	尚未支援	請從 OpenAPI 文件中移除這項設定。API Gateway 不支援 OpenAPI 3.x 中的這項功能。

建立新的 API 設定

使用修改後的 OpenAPI 3.x 文件建立新的 API 設定。

1. 建立 API 設定：

   gcloud api-gateway api-configs create NEW_CONFIG_ID --api=API_ID --project=PROJECT_ID --openapi-spec=NEW_API_DEFINITION
   

   更改下列內容：

   • NEW_CONFIG_ID：API 設定的新 ID。
   • API_ID：API 的 ID。
   • PROJECT_ID：您的 Google Cloud 專案 ID
   • NEW_API_DEFINITION：OpenAPI 3.x 規格檔案的路徑。

更新閘道

更新閘道執行個體，從修改後的 OpenAPI 3.x 文件參照新的 API 設定。

1. 更新閘道：

   gcloud api-gateway gateways update GATEWAY_ID --api-config=API_CONFIG --project=PROJECT_ID --location=GATEWAY_LOCATION
   

   更改下列內容：

   • GATEWAY_ID：閘道的 ID。
   • API_CONFIG：新 API 設定的完整資源路徑，例如： projects/PROJECT_ID/locations/global/apis/API_ID/configs/NEW_CONFIG_ID
   • PROJECT_ID：您的 Google Cloud 專案 ID
   • GATEWAY_LOCATION：閘道位置。

後續步驟

• 進一步瞭解 API Gateway。
• 瞭解 OpenAPI 規範。