OpenAPI 3.x を使用するようにゲートウェイを変更する

このページでは、API 構成に OpenAPI 3.x 仕様を使用するように既存の API ゲートウェイを変更する方法について説明します。

始める前に

• OpenAPI 2.0 仕様で構成された既存の API Gateway インスタンスがあることを確認します。
• gcloud CLI をインストールします。詳細については、Google Cloud CLI をインストールするをご覧ください。

OpenAPI 3.x を使用するように API 構成を変更する

既存の 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。

   出力には、OpenAPI ドキュメントの base64 でエンコードされたコンテンツを含む openapiDocuments セクションが表示されます。

   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 Editor には変換ユーティリティが用意されています。

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 仕様を確認する。