Google Cloud API Gateway のスキーマ定義を FastAPI で作成する¶

Google Cloud API Gateway を使って API を公開する際に、API のスキーマ定義を FastAPI で作成した。2024 年 4 月頃の構成記録として、作成手順を紹介する。

Google Cloud API Gateway¶

Google Cloud API Gateway は、Google Cloud の WebAPI を公開するためのマネージドサービス。API Gateway を使うことで、API の認証、認可、トラフィック制御、モニタリングなどを簡単に設定できる。

当時調べた API Gateway は Swagger v2 にしか対応していなかったため、この形式でスキーマを用意した。

FastAPI で API を作成する¶

FastAPI は、Python の WebAPI フレームワークだ。FastAPI で作成した API のスキーマ定義を OpenAPI v3 で出力できる。当時の API Gateway に渡すには、FastAPI で作成したスキーマ定義を Swagger v2 に変換する必要があった。

変換までの手順は次のとおりだ。

FastAPI で API を作成する
各エンドポイントのスキーマ定義を作成し、x-google-backendやsecurityなどの API Gateway で使用する拡張プロパティをopenapi_extraを使って追加する
fastapi_swagger2 ライブラリを使用して、FastAPI のスキーマ定義を Swagger v2 に変換する
online validator を使って、Swagger v2 のスキーマ定義を確認する

openapi_extra で API Gateway 用の拡張プロパティを追加する¶

openapi_extraに追加したプロパティは、FastAPI で作成したスキーマ定義を Swagger v2 に変換すると、そのまま出力される。FastAPI で作成したスキーマ定義を API Gateway で使用できる。

@app.get(
    "/health",
    status_code=200,
    openapi_extra={
        "security": [{"api_key": []}],
        "x-google-backend": {"address": r"${CLOUD_RUN_SERVICE}/health"},
    },
)
def health():
    return {"status": "ok"}

FastAPI で作成したスキーマ定義を Swagger v2 に変換する¶

FastAPI で作成したスキーマ定義を Swagger v2 に変換するため、fastapi_swagger2 を使用した。fastapi_swagger2 は、FastAPI のスキーマ定義を OpenAPI v3 から Swagger v2 に変換するライブラリだ。

from fastapi_swagger2 import FastAPISwagger2
from .api import app

FastAPISwagger2(app)
app.servers = None # エラー回避
print(app.swagger2())

online validator で Swagger v2 のスキーマ定義を確認する¶

OpenAPI v3 から Swagger v2 に変換したスキーマが仕様を満たしていないことがある。そのため、online validator を使って、Swagger v2 のスキーマ定義を確認するとよい。

まとめ¶

今回の構成では、FastAPI が出力する OpenAPI v3 のスキーマを fastapi_swagger2 で Swagger v2 へ変換した。ただし、変換後のスキーマが仕様を満たしているとは限らないため、online validator での確認を挟む手順が安全だ。openapi_extraで追加したx-google-backendなどの拡張プロパティも変換後にそのまま残るので、API Gateway 固有の設定は FastAPI 側にまとめて書けるとわかった。