概要

Google Cloud API GatewayはやっとOpenAPI v3に対応した。
(日本語ドキュメントは記載なし。英語ドキュメントには3.0.x対応が明記されている。2025-10-19現在。)

これによりOpenAPI v3の表現力をGoogle Cloud API Gatewayでも享受できる。
まだ記載が少ないため、移行方法を日本語で残す。

想定構成

今回はAPI Gatewayのバックエンドとして、Cloud Runを用いる。

  • 内容はstatusとtimestampを返すだけの単純なAPI。
  • Cloud Run エンドポイント: https://sample.run.app (Cloud RunコンソールやCLIで確認できる)
  • これまでは以下の構成でOpenAPI v2を用いてデプロイしていた。

既存コード

swagger: '2.0'
info:
  title: Sample API
  description: API for short sample.
  version: 0.0.1
schemes:
  - https
produces:
  - application/json
paths:
  /sample:
    get:
      summary: Sample Endpoint
      operationId: sample
      x-google-backend:
        address: https://sample.run.app
      responses:
        '200':
          description: A successful response
          schema:
            type: object
            properties:
              status:
                type: string
              timestamp:
                type: string

変換先

  • 仕様としては変化させない。Cloud Run エンドポイントも上記と同じ。
  • OpenAPI v3を使う。
openapi: 3.0.0
info:
  title: Sample API
  description: API for short sample.
  version: 0.0.1
x-google-api-management:
  backends:
    cloudrun_backend:
      address: https://sample.run.app
paths:
  /sample:
    get:
      x-google-backend: cloudrun_backend
      summary: Sample Endpoint
      operationId: sample
      responses:
        "200":
          description: A successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  timestamp:
                    type: string

移行手順

以下3ステップで簡単に実現できる。

Step 1. OpenAPI v2のyamlファイルを入手

Google公式ドキュメントでは実際のAPI構成からダウンロードしている。
とはいえ、API Gatewayを利用する場合、既存のOpenAPI v2コードが手元にあるのが自然な気もするので深くは述べない。

Step 2. OpenAPI v2をOpenAPI v3に変換する

一旦機械的にv2をv3に変換する。SwaggerEditorを使ってもいい。
今回はswagger2openapiを使っている。

npx swagger2openapi [変換前] -o [変換後]

すると、以下の変換前コードが

変換前のコード例
swagger: '2.0'
info:
  title: Sample API
  description: API for short sample.
  version: 0.0.1
schemes:
  - https
produces:
  - application/json
paths:
  /sample:
    get:
      summary: Sample Endpoint
      operationId: sample
      x-google-backend:
        address: https://sample.run.app
      responses:
        '200':
          description: A successful response
          schema:
            type: object
            properties:
              status:
                type: string
              timestamp:
                type: string

以下の様になる。

変換後のコード例
openapi: 3.0.0
info:
  title: Sample API
  description: API for short sample.
  version: 0.0.1
paths:
  /sample:
    get:
      summary: Sample Endpoint
      operationId: sample
      # 次のステップでこの x-google-backend 設定を移動する
      x-google-backend:
        address: https://sample.run.app
      responses:
        "200":
          description: A successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  timestamp:
                    type: string

Step 3. YAMLの修正

ドキュメントに従い、x-google-...で始まる部分を修正する。

ポイントは以下。

  1. x-google-backend以下をx-google-api-managementのbackends( ※複数形 ) に移す。
  2. x-google-api-managementに移したそれぞれのbackendには名前を付ける。
  3. これまでのx-google-backendの箇所には、そのbackendの名前を参照する様にする。

例えば、以下の様に対応する。

  1. address: ...をx-google-api-managementのbackendsに移した。
  2. そのbackendにcloudrun_backendと名前をつけた。
  3. これまで/sampleのgetで指定していたx-google-backendから、cloudrun_backendを参照している。
修正後の最終コード
openapi: 3.0.0
info:
  title: Sample API
  description: API for short sample.
  version: 0.0.1
x-google-api-management:
  # 複数形になる
  backends:
    # 変換前のx-google-backendをここに移動
    # cloudrun_backend と言う名前をつけた
    cloudrun_backend:
      address: https://sample.run.app
paths:
  /sample:
    get:
      # 上記の cloudrun_backend を参照
      x-google-backend: cloudrun_backend
      summary: Sample Endpoint
      operationId: sample
      responses:
        "200":
          description: A successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  timestamp:
                    type: string

これでv3で動くGoogle Cloud API Gateway構成ができた。

出典

OpenAPI overview | API Gateway | Google Cloud Documentation
Modify a gateway to use OpenAPI 3.x | API Gateway | Google Cloud Documentation

更新履歴

2025-11-20 細かな表現を修正。