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

Google Cloud API Gateway を使って API を公開する際に、API のスキーマ定義を FastAPI で作成した。その備忘録。

Google Cloud API Gateway¶

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

API Gateway は、Swagger v2 のスキーマ定義を使用して API を定義する。Swagger v2 は、OpenAPI v3 に移行することが推奨されており、世の中では OpenAPI v3 が主流になっているが API Gateway は Swagger v2 にしか対応していない。

FastAPI でスキーマ定義を作成する¶

FastAPI は、Python の WebAPI フレームワーク。FastAPI で作成した API のスキーマ定義を OpenAPI v3 で出力できる。しかし、API Gateway は Swagger v2 にしか対応していないため、FastAPI で作成したスキーマ定義を Swagger v2 に変換する必要がある。

FastAPI で作成したスキーマ定義を Swagger v2 に変換するために、次の手順でスキーマ定義を作成した。

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

@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 のスキーマ定義を OpenAPI v3 から Swagger v2 に変換するライブラリ。

1
2
3
4
5
6

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 のスキーマ定義を確認するとよい。

• Swagger Editor
• Swagger/OpenAPI online validator