api-gateway-openapi-spec-authoring

API Gateway OpenAPI 仕様の作成

API Gateway は、OpenAPI 2.0、3.0.x、3.1.x の API 設定を受け付けます。OpenAPI 3.x の Google 拡張機能は、OpenAPI 2.0 の拡張機能とは構造が異なります。

• 必須のルート x-google-api-management ブロックでバックエンドを指定します。
• x-google-backend は、これらのバックエンドのいずれかを参照する文字列です。
• JWT の設定は x-google-auth に移動します。メトリクスと割り当ては x-google-api-management に移動します。

このスキルを使用して、OpenAPI 2.0 仕様を移行する、新しい OpenAPI 3.x 仕様を作成する、または作成に失敗する API 設定を修正します。

クレジット表記

必ずお読みください：gcloud、REST API、または MCP のコマンドを実行する前に、必ず使用状況のクレジット表記をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコード内では実行しない）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:api-gateway-openapi-spec-authoring)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:api-gateway-openapi-spec-authoring) を追加してください。

前提条件

1. ツールをインストールします。
   • Google Cloud CLI をインストールします。その後、gcloud components update で更新します。**理由：**古い CLI では、OpenAPI 3.x の API 設定のアップロードに失敗する場合があります。
   • Python 3.10 以降と、バリデーター スクリプト用の PyYAML をインストールします。JSON 仕様では PyYAML は不要です。

     pip install "PyYAML>=6.0,<7.0"
     

2. 認証を行い、プロジェクト、課金、ロケーションを選択します。
   • gcloud auth login を実行します。
   • gcloud config set project {project_id} でプロジェクトを選択するか、gcloud projects create {project_id} で作成します。
   • 有効な課金アカウントが {project_id} にリンクされていることを確認します。API Gateway には API 呼び出しの月間無料枠がありますが、有効な課金アカウントが必要です。最新の料金については、API Gateway の料金をご覧ください。
   • ゲートウェイ コマンドのデフォルトの --location には us-central1 を使用します。その他の対応リージョンについては、API Gateway のデプロイモデルをご覧ください。
3. 必要な Google Cloud API を有効にします。

   gcloud services enable \
     apigateway.googleapis.com \
     servicemanagement.googleapis.com \
     servicecontrol.googleapis.com \
     --project={project_id}
   

4. IAM ロールを確認します（各手順で最も制限の厳しいロールを使用してください）。
   • API、API 設定、ゲートウェイを作成および更新するには、{project_id} で API Gateway 管理者（roles/apigateway.admin）が必要です。
   • gcloud services enable コマンドを実行するには、{project_id} で Service Usage 管理者（roles/serviceusage.serviceUsageAdmin）が必要です。
   • API 設定でゲートウェイのサービス アカウントを参照するには、{gateway_sa_email} でサービス アカウント ユーザー（roles/iam.serviceAccountUser）が必要です。
   • 認証が必要な Cloud Run バックエンドの場合は、サービスに対する Cloud Run 起動元ロール（roles/run.invoker）を {gateway_sa_email} に付与します。

判断マトリクス

タスク	必要な仕組み	重要なガードレール	詳細なリファレンス
OpenAPI 2.0（swagger: "2.0"）の設定を移行する	標準フィールドを変換してから、各 Google 拡張を OpenAPI 3.x の形式に移行します。	Swagger Editor などのコンバーターでは、すべての x-google-* 拡張が OpenAPI 2.0 の形式のまま残ります。また、x-google-endpoint のない servers が書き込まれるため、API のベースパスが失われます。理由： API Gateway は、3.x の仕様でほとんどの OpenAPI 2.0 拡張を使用すると、The '{extension}' extension is only supported in OpenAPI 2.x を返して拒否します。	OpenAPI 2.0 から 3.x への移行
リクエストをバックエンドにルーティングする	ルートの x-google-api-management.backends.{backend_name} と、ルートまたはオペレーションの x-google-backend: {backend_name}	すべてのバックエンドで pathTranslation を設定します。理由： ルートの x-google-backend ではデフォルトが APPEND_PATH_TO_ADDRESS ですが、オペレーションレベルのものでは CONSTANT_ADDRESS です。CONSTANT_ADDRESS はすべてのリクエストを変更せずにアドレスへ送信し、パスパラメーターはクエリパラメーターとして送信します。APPEND_PATH_TO_ADDRESS はベースパスを含むリクエストパス全体を追加します。パス項目に x-google-backend を設定してはいけません。API Gateway に拒否されます。	拡張機能と制限
呼び出し元を認証する	JWT：x-google-auth（issuer、jwksUri、audiences）を含む type: oauth2 スキーム。API キー：ヘッダーの x-api-key、またはクエリの key もしくは api_key を含む type: apiKey スキーム。	API Gateway は OAuth スコープを確認しません。security リストでは、すべての選択肢（OR）に API キーを含めるか、どの選択肢にも含めないでください。1 つの要件オブジェクトに 2 つの JWT スキームを含めてはいけません（AND）。理由： API Gateway はこれらの組み合わせを拒否します。JWT と API キーを選択肢にする場合など、ユーザーがこれらのいずれかを求めても、仕様には記述しないでください。このルールを説明し、すべての選択肢に API キーを含める方法や、呼び出し元の種類ごとにパスを分ける方法など、サポートされている選択肢を記述してください。	拡張機能と制限
割り当て量を追加する	x-google-api-management.metrics と quota.limits、および各オペレーションの x-google-quota: {metric_name: cost}	ルートまたはパスレベルの x-google-quota に依存してはいけません。理由： OpenAPI 3.x では、API Gateway はエラーを出さずにこの設定を無視します。割り当て量を設定する各オペレーションで API キーを必須にし、すべての API 設定で各メトリクス名を同じにしてください。	拡張機能と制限
ベースパスと CORS を設定する	x-google-endpoint を含む servers エントリを 1 つ設定します（例：url: /v1）。	API Gateway は x-google-endpoint のない servers エントリを無視します。allowCors: true は、CORS リクエストをバックエンドに渡すだけです。理由： ゲートウェイは CORS ヘッダーを追加しないため、バックエンドが応答する必要があります。	拡張機能と制限
api-configs create の失敗を修正する	エラーメッセージをエラーテーブルと照合し、仕様を修正します。	IAM に関するエラー、または別の api-configs create が実行される場合を除き、再試行する前に仕様を修正してください。理由： 同じ仕様に対して API Gateway は同じエラーを返します。	API 設定エラー
オペレーションを MCP ツールとして公開する	api-gateway-mcp-server スキル	MCP では、ツール名、説明、tools/list のセキュリティに関するルールが追加されます。そのスキルがインストールされていない場合は、このスキルを OpenAPI 3.x の仕様に使用し、MCP 拡張機能については MCP の設定ガイドに従ってください。	-

実行ワークフローと検証ループ

1. 現在の仕様を取得します：
   • ユーザーのリポジトリにある仕様ファイルを使用します。ファイルがない場合は、ゲートウェイの有効な API 設定を確認します：

     gcloud api-gateway gateways describe {gateway_id} --location={region} --project={project_id} --format="value(apiConfig)"
     

   • 出力は projects/{project}/locations/global/apis/{api_id}/configs/{config_id} です。その設定の仕様を表示します：

     gcloud api-gateway api-configs describe {config_id} --api={api_id} --project={project_id} --view=FULL \
       --format="value(openapiDocuments[0].document.contents)" | tr '_-' '/+' | base64 --decode
     

   • gcloud は内容を URL セーフな Base64 で出力するため、tr は base64 --decode の前に 2 つの文字を変換します。設定に OpenAPI ドキュメントが複数ある場合は、[0] を [1]、[2] などに変更します。
2. OpenAPI 3.x の仕様を作成します：
   • OpenAPI 2.0 の仕様の場合は、OpenAPI 2.0 から 3.x への移行に従い、結果を完全な変換例と比較します。
   • 新しい仕様の場合は、拡張機能と制限事項のテンプレートから始めます。
   • openapi を 3.0.x または 3.1.x のバージョンに設定します。例では 3.0.4 を使用しています。OpenAPI 3.1 では、各スキーマに type を 1 つ指定します。理由： API Gateway は type: ["string", "null"] のような型のリストを拒否します。
   • 各オペレーションに一意の operationId と responses オブジェクトを設定し、ローカルの $ref 値のみを使用します。理由： API Gateway は、operationId または responses のないオペレーション、getItem と get-Item のように同じメソッド名になる 2 つの operationId、および URL への $ref を拒否します。
3. 回答または API 設定の作成前に、作成または変更するすべての仕様に対して決定論的な検証ループを実行します：

   python3 scripts/validate_apigw_openapi.py --spec={spec_file}
   

   • スクリプトのパスは、このスキルのディレクトリからの相対パスです。返信で仕様のみを返す場合は、一時ファイルに書き込み、回答前にそのファイルに対してスクリプトを実行します。
   • スクリプトがコード 1（"status": "FAIL"）で終了した場合は、{spec_file} のすべてのエラーを修正し、スクリプトを再実行します。コード 0（"status": "PASS"）で終了するまで続けます。
   • スクリプトがコード 2 で終了した場合は、stderr に表示されたファイルパスまたは YAML／JSON 構文エラーを修正するか、PyYAML をインストールします。
   • pathTranslation のないバックエンド、API キーのないオペレーションに設定された割り当て、allowCors など、すべての警告を確認します。修正するか、そのまま残す理由をユーザーに伝えます。
   • スクリプトはすべてのルールを確認するわけではありません。PASS は、このスキルで説明する API Gateway の問題が見つからなかったことを意味します。存在しないスキーマへの $ref など、OpenAPI 全般の妥当性は確認しません。理由： API Gateway が仕様を受け入れることを確認できるのは、手順 5 の api-configs create のみです。スクリプトが PASS したからといって、仕様をデプロイできるとユーザーに伝えないでください。
4. 仕様をユーザー向けに要約し、デプロイ前に承認を得ます。 以下の各点を伝えます：
   • 移動または削除した OpenAPI 2.0 の拡張機能（OpenAPI 3.x でサポートされない x-google-allow など）。追加した operationId や修正したアドレスなど、その他の変更もそれぞれ伝えます。
   • 各バックエンドの pathTranslation（スクリプト出力の backend_path_translation）と、パスパラメーターがクエリパラメーターとしてバックエンドに送信されるようになった各オペレーション（path_parameters_as_query）。APPEND_PATH_TO_ADDRESS の場合、バックエンドにはベースパスも送信されます。
   • JWT または API キーが必要なオペレーション、ID トークンとそのオーディエンスを受け取るバックエンド、および API Gateway は OAuth スコープを確認しないこと。
   • 割り当て指標と上限、および各指標名が現在の API 設定と一致すること。
5. 新しい API 設定を作成し、ゲートウェイを更新します（本番ゲートウェイを更新する前に、担当者の承認を得てください）：

   gcloud api-gateway api-configs create {new_config_id} \
     --api={api_id} \
     --openapi-spec={spec_file} \
     --backend-auth-service-account={gateway_sa_email} \
     --project={project_id}
   
   gcloud api-gateway gateways update {gateway_id} \
     --api={api_id} \
     --api-config={new_config_id} \
     --location={region} \
     --project={project_id}
   

   • 新しいゲートウェイの場合は、gateways update の代わりに同じフラグを指定して gcloud api-gateway gateways create {gateway_id} を実行します。api-configs create は、存在しない場合に API を作成します。
   • オペレーションに API キーが必要な場合は、API のマネージドサービスを有効にします。gcloud api-gateway apis describe {api_id} --project={project_id} --format="value(managedService)" で名前を取得し、gcloud services enable {managed_service} --project={project_id} を実行します。また、API 用の API キーを作成する各プロジェクトでも有効にします。
   • 既存の API 設定の仕様は変更できないため、変更ごとに新しい設定 ID を使用します。
   • API ごとに一度に実行する api-configs create は 1 つにし、完了するまで待ちます。大規模な API 設定の作成には最大 10 分かかることがあります。
   • api-configs create が失敗した場合は、API 設定のエラーでエラーテキストを確認し、仕様を修正して手順 3 に戻ります。
   • 新しい API 設定でトラフィックを処理できるようになるまで、以前の API 設定を保持します。ロールバックするには、以前の設定 ID を指定して gateways update を実行します。
6. ゲートウェイを確認します：
   • gcloud api-gateway gateways describe {gateway_id} --location={region} --project={project_id} --format="value(state,defaultHostname)" を実行し、状態が ACTIVE になるまで待ちます。
   • 変更した各パスに https://{default_hostname}{base_path}{path} でリクエストを送信し、オペレーションに必要な認証情報を指定します。バックエンドが想定どおりのパスとパラメーターを受け取ることを確認します。
   • HTML の 404 Page not found は、ゲートウェイの準備ができていないことを示します。最後の作成または更新が完了していることを確認し、設定を変更する前に再試行します。ゲートウェイの更新中も、一部のリクエストは以前の API 設定に到達することがあります。JSON の 404（The current request is not defined by this API.）は、有効な API 設定にそのパスが定義されていないことを示します。

デプロイ前チェックリスト

• openapi が 3.0.x または 3.1.x であり、セキュリティスキーム上の x-google-management、x-google-endpoints、x-google-api-name、x-google-allow、x-google-issuer など、OpenAPI 2.0 の拡張機能が仕様に含まれていないこと。
• x-google-api-management.backends ですべてのバックエンドが定義され、すべての x-google-backend がそのいずれかを指定する文字列であり、パス項目に x-google-backend が設定されていないこと。
• すべてのバックエンドに pathTranslation が設定されていること。
• すべての操作に一意の operationId と responses オブジェクトがあり、各パス変数に in: path および required: true を指定したパラメーターがあること。
• すべての x-google-quota が API キーを必要とする操作に設定され、すべてのメトリクス名が現在の API 設定と一致していること。
• servers エントリのうち x-google-endpoint を持つものが最大 1 つであり、その URL にカスタムポートが含まれていないこと。
• python3 scripts/validate_apigw_openapi.py --spec={spec_file} が "status": "PASS" を返すこと（終了コード 0）。

リソースのクリーンアップ

テスト環境を削除する際に継続的な料金が発生しないよう、人による承認を求め、依存関係の順にリソースを削除してください。

gcloud api-gateway gateways delete {gateway_id} --location={region} --project={project_id}
gcloud api-gateway api-configs delete {config_id} --api={api_id} --project={project_id}
gcloud api-gateway apis delete {api_id} --project={project_id}