概要

Google Cloud API GatewayはやっとOpenAPI v3に対応した。
これに伴いOpenAPI v3の表現力をGoogle Cloud API Gatewayでも享受できる。
まだ記載が少ないため、移行方法を日本語で残しておく。

想定構成

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

  • 内容としてはstatusとtimestampを返すだけの単純なもの。
  • 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:
  /health:
    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.4
info:
  title: Sample API
  description: API for short sample.
  version: 0.0.2
x-google-api-management:
  backends:
    cloudrun_backend:
      address: https://sample.run.app
paths:
  /health:
    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:
  /health:
    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:
  /health:
    get:
      summary: Sample Endpoint
      operationId: sample
      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で始まる部分を修正する。

ポイントは以下。

  • x-google-backendをx-google-api-managementのbackends(複数形になることに注意。バックエンドを纏めて記載するため。)セクションに移す。
  • x-google-api-managementに移したそれぞれのbackendには名前を付ける。
  • これまでのx-google-backendの箇所には、そのbackendの名前を参照する様にする。

例えば以下実例では、

  • これまでx-google-backendに記載していたaddress: https://sample.run.appをx-google-api-managementのbackendsに移している。
  • 加えて、そのbackendにcloudrun_backendと名前をつけている。
  • これまで/healthのgetで指定していたx-google-backendから、cloudrun_backendを参照している。
修正後の最終コード
openapi: 3.0.4
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:
  /health:
    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

これで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