FastAPIとSwagger: スキーマを非表示にする方法

FastAPIとSwaggerの統合

FastAPIは、Pythonの非常に高速な（高性能）、使いやすい、モダンで、高速（リアルタイム）のWebフレームワークです。これは、APIの構築に最適なツールであり、Swagger/OpenAPIのようなツールとの統合が容易です。

Swagger（現在はOpenAPIとして知られています）は、RESTful APIを設計、構築、文書化、および使用するためのツールセットです。Swagger UIは、Swaggerから生成されたAPI定義を視覚化し、ユーザーがAPIと対話できるようにするWebベースのインターフェースです。

FastAPIとSwaggerを統合すると、APIのエンドポイントを視覚化し、直接ブラウザからAPIをテストできます。これは、APIの開発とデバッグを大幅に簡単にします。

FastAPIを使用すると、Pythonの型ヒントを使用してリクエストとレスポンスのスキーマを定義します。これらのスキーマは、Swagger UIで使用されるOpenAPI定義を自動的に生成します。

以下に、FastAPIとSwaggerを統合する基本的なコードスニペットを示します。

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

このコードを実行すると、http://localhost:8000/docsにアクセスすることでSwagger UIを表示できます。このUIでは、/items/{item_id}エンドポイントが表示され、直接ブラウザからテストリクエストを送信できます。

FastAPIとSwaggerの統合は、APIの開発を効率化し、エンドユーザーに対するAPIの可視性と使いやすさを向上させます。次のセクションでは、特定のスキーマをSwagger UIから非表示にする方法について説明します。。

@Schema(hidden=True)の使用

FastAPIでは、Pythonの型ヒントとPydanticモデルを使用してリクエストとレスポンスのスキーマを定義します。これらのスキーマは、Swagger UIで使用されるOpenAPI定義を自動的に生成します。

しかし、特定のフィールドやモデルをSwagger UIから非表示にしたい場合があります。これは、@Schemaデコレータとhidden=Trueパラメータを使用して実現できます。

以下に、@Schema(hidden=True)の使用例を示します。

from pydantic import BaseModel, Schema

class Item(BaseModel):
    name: str = Schema(..., title="The name of the item")
    description: str = Schema(None, title="The description of the item", hidden=True)
    price: float = Schema(..., title="The price of the item")

この例では、descriptionフィールドはSwagger UIから非表示になります。つまり、Swagger UIの対話型ドキュメンテーションではdescriptionフィールドは表示されません。

@Schema(hidden=True)は、内部的な詳細を非表示にしたり、エンドユーザーにとって混乱を招く可能性のある情報を隠したりするのに便利です。ただし、この機能は適切に使用することが重要です。APIの透明性と利便性を維持するために、必要な情報を非表示にしないように注意してください。。

Swagger UIパラメータの調整

Swagger UIは、APIのエンドポイントとその詳細を視覚化するための強力なツールです。しかし、デフォルトの設定では、すべてのエンドポイントとスキーマが表示されます。特定のエンドポイントやスキーマを非表示にしたい場合や、UIの見た目をカスタマイズしたい場合は、Swagger UIのパラメータを調整することができます。

FastAPIでは、FastAPIインスタンスの作成時にopenapi_urlパラメータを設定することで、Swagger UIの設定を調整することができます。以下に、openapi_urlパラメータを使用してSwagger UIをカスタマイズする例を示します。

from fastapi import FastAPI

app = FastAPI(openapi_url="/api/v1/openapi.json")

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

この例では、OpenAPIスキーマのURLが/api/v1/openapi.jsonに設定されています。これにより、Swagger UIはこのURLからスキーマを読み込みます。

また、FastAPIのFastAPIクラスは、Swagger UIの設定を追加または上書きするためのswagger_ui_init_oauthメソッドも提供しています。これを使用すると、OAuth2.0の設定など、Swagger UIの詳細な設定を調整することができます。

これらの機能を使用することで、Swagger UIの表示をより詳細に制御し、APIのドキュメンテーションをより効果的に管理することができます。次のセクションでは、カスタムOpenAPIスキーマの生成について説明します。。

カスタムOpenAPIスキーマの生成

FastAPIは、Pythonの型ヒントとPydanticモデルを使用してリクエストとレスポンスのスキーマを定義します。これらのスキーマは、Swagger UIで使用されるOpenAPI定義を自動的に生成します。

しかし、特定の要件を満たすためにOpenAPIスキーマをカスタマイズしたい場合があります。FastAPIでは、FastAPIインスタンスのopenapi_schemaプロパティをオーバーライドすることで、カスタムOpenAPIスキーマを生成することができます。

以下に、カスタムOpenAPIスキーマの生成例を示します。

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        description="This is a very custom OpenAPI schema",
        routes=app.routes,
    )
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app = FastAPI()

app.openapi = custom_openapi

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

この例では、custom_openapi関数を定義し、FastAPIインスタンスのopenapiメソッドをオーバーライドしています。この関数は、get_openapi関数を使用してOpenAPIスキーマを生成し、そのスキーマをカスタマイズします。

このようにして生成されたカスタムOpenAPIスキーマは、Swagger UIで表示されます。これにより、APIのドキュメンテーションをより詳細に制御し、特定の要件を満たすことができます。次のセクションでは、FastAPIインスタンスのinclude_in_schemaパラメータについて説明します。。

FastAPIインスタンスのinclude_in_schemaパラメータ

FastAPIでは、APIのエンドポイントを定義する際に、そのエンドポイントがOpenAPIスキーマ（そしてSwagger UI）に含まれるかどうかを制御することができます。これは、エンドポイントの定義にinclude_in_schemaパラメータを使用して行います。

以下に、include_in_schemaパラメータの使用例を示します。

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}", include_in_schema=False)
async def read_item(item_id: int):
    return {"item_id": item_id}

この例では、/items/{item_id}エンドポイントはOpenAPIスキーマに含まれず、Swagger UIにも表示されません。

include_in_schemaパラメータは、特定のエンドポイントをドキュメンテーションから非表示にしたい場合や、内部的なエンドポイントを隠したい場合に便利です。ただし、この機能は適切に使用することが重要です。APIの透明性と利便性を維持するために、必要な情報を非表示にしないように注意してください。。