OpenAPIの拡張¶
生成されたOpenAPIスキーマを変更する必要がある場合があります。
このセクションではその方法を説明します。
通常のプロセス¶
通常の（デフォルトの）プロセスは以下のとおりです。
FastAPIアプリケーション（インスタンス）には、OpenAPIスキーマを返すことが期待される.openapi()メソッドがあります。
アプリケーションオブジェクトの作成の一部として、/openapi.json（またはopenapi_urlに設定したもの）のパス操作が登録されます。
これは、アプリケーションの.openapi()メソッドの結果を含むJSONレスポンスを返すだけです。
デフォルトでは、.openapi()メソッドは.openapi_schemaプロパティに内容があるかどうかを確認して返します。
内容がない場合は、fastapi.openapi.utils.get_openapiのユーティリティ関数を使用して生成します。
そして、その関数get_openapi()は次のパラメータを受け取ります。
title: ドキュメントに表示されるOpenAPIタイトル。version: APIのバージョン、例:2.5.0。openapi_version: 使用されるOpenAPI仕様のバージョン。デフォルトは最新:3.1.0。summary: APIの簡単な概要。description: APIの説明。Markdownを含めることができ、ドキュメントに表示されます。routes: ルートのリスト。これらは登録されたパス操作のそれぞれです。app.routesから取得されます。
情報
summaryパラメータは、OpenAPI 3.1.0以降で利用可能であり、FastAPI 0.99.0以降でサポートされています。
デフォルトのオーバーライド¶
上記の情報を使用して、同じユーティリティ関数を使用してOpenAPIスキーマを生成し、必要な各部分をオーバーライドできます。
たとえば、カスタムロゴを含めるためのReDocのOpenAPI拡張を追加しましょう。
通常のFastAPI¶
まず、すべてのFastAPIアプリケーションを通常どおりに記述します。
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"name": "Foo"}]
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Custom title",
version="2.5.0",
summary="This is a very custom OpenAPI schema",
description="Here's a longer description of the custom **OpenAPI** schema",
routes=app.routes,
)
openapi_schema["info"]["x-logo"] = {
"url": "https://fastapi.dokyumento.jp/img/logo-margin/logo-teal.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
OpenAPIスキーマの生成¶
次に、同じユーティリティ関数を使用してOpenAPIスキーマを生成します。これはcustom_openapi()関数内で行います。
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"name": "Foo"}]
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Custom title",
version="2.5.0",
summary="This is a very custom OpenAPI schema",
description="Here's a longer description of the custom **OpenAPI** schema",
routes=app.routes,
)
openapi_schema["info"]["x-logo"] = {
"url": "https://fastapi.dokyumento.jp/img/logo-margin/logo-teal.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
OpenAPIスキーマの変更¶
これで、ReDoc拡張機能を追加して、OpenAPIスキーマのinfo「オブジェクト」にカスタムx-logoを追加できます。
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"name": "Foo"}]
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Custom title",
version="2.5.0",
summary="This is a very custom OpenAPI schema",
description="Here's a longer description of the custom **OpenAPI** schema",
routes=app.routes,
)
openapi_schema["info"]["x-logo"] = {
"url": "https://fastapi.dokyumento.jp/img/logo-margin/logo-teal.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
OpenAPIスキーマのキャッシュ¶
.openapi_schemaプロパティを生成されたスキーマを保存するための「キャッシュ」として使用できます。
これにより、ユーザーがAPIドキュメントを開くたびにアプリケーションがスキーマを生成する必要がなくなります。
スキーマは一度だけ生成され、次のリクエストでは同じキャッシュされたスキーマが使用されます。
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"name": "Foo"}]
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Custom title",
version="2.5.0",
summary="This is a very custom OpenAPI schema",
description="Here's a longer description of the custom **OpenAPI** schema",
routes=app.routes,
)
openapi_schema["info"]["x-logo"] = {
"url": "https://fastapi.dokyumento.jp/img/logo-margin/logo-teal.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
メソッドのオーバーライド¶
これで、.openapi()メソッドを新しい関数に置き換えることができます。
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"name": "Foo"}]
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Custom title",
version="2.5.0",
summary="This is a very custom OpenAPI schema",
description="Here's a longer description of the custom **OpenAPI** schema",
routes=app.routes,
)
openapi_schema["info"]["x-logo"] = {
"url": "https://fastapi.dokyumento.jp/img/logo-margin/logo-teal.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
確認¶
http://127.0.0.1:8000/redocにアクセスすると、カスタムロゴ（この例ではFastAPIのロゴ）を使用していることがわかります。
