FastAPIのSwagger UI（/docs）自動生成｜表示・カスタマイズ・本番で無効化する手順

FastAPIは FastAPI() のインスタンスを作成するだけでSwagger UI（/docs エンドポイント）を自動生成し、ブラウザからAPIをその場でテストできます。この記事では、Swagger UIの表示手順、title や swagger_ui_parameters によるカスタマイズ、OAuth2認証の組み込み、そして本番環境で /docs を保護・無効化する方法までを、コード付きで解説します。

まとめ：FastAPIのSwagger UI（/docs）要点

• 自動生成：FastAPI() を作るだけで /docs にSwagger UI、/redoc にReDoc、/openapi.json にOpenAPIスキーマが生成される（追加設定不要）。
• 表示手順：uvicorn main:app --reload で起動し、http://127.0.0.1:8000/docs にアクセスする。
• カスタマイズ：タイトルやバージョンは FastAPI(title=..., version=...)、UIの挙動（モデル展開など）は swagger_ui_parameters で調整する。
• 本番対策：公開したくない場合は FastAPI(docs_url=None, redoc_url=None) で無効化するか、OAuth2などの認証で保護する。

FastAPIとSwagger UIの連携方法とそのメリット

FastAPIは、Pythonで書かれた高速なWebフレームワークで、効率的な開発とパフォーマンスの高さで注目されています。一方、Swagger UIはAPIドキュメントの自動生成と視覚化を提供するツールです。これらを連携することで、開発者は迅速にAPIを構築し、その動作を視覚的に確認できるようになります。この連携により、APIの開発プロセスが大幅に効率化され、ドキュメントの管理が容易になります。以下に、FastAPIとSwagger UIの連携方法とそのメリットについて詳しく解説します。

FastAPIとは？その基本と概要

FastAPIは、StarletteやPydanticといった優れたPythonライブラリを基盤に構築されたWebフレームワークです。非同期サーバーとしてのパフォーマンスの高さや、開発速度の向上を目指して設計されています。Pythonタイプヒントを活用することで、自動的にデータの検証やシリアライズが行われ、バグの少ないコードを書くことが可能です。

Swagger UIとは？その役割と機能

Swagger UIは、Swagger仕様に基づいてAPIのドキュメントを生成するツールです。ユーザーフレンドリーなインターフェースを提供し、APIのエンドポイントやパラメータ、レスポンスの詳細を視覚的に確認できます。また、Swagger UIを利用することで、APIのテストやデバッグも容易になります。

FastAPIとSwagger UIを連携するメリット

FastAPIとSwagger UIを連携することで得られる最大のメリットは、開発効率の向上とドキュメントの自動化です。APIの変更に伴うドキュメントの更新作業が自動化されるため、手動でのミスが減り、最新の状態を常に保つことができます。また、Swagger UIを使うことで、開発者やクライアントがAPIの仕様を簡単に確認し、利用することが可能になります。

FastAPIとSwagger UIの基本的な設定方法

FastAPIとSwagger UIの連携は非常に簡単です。FastAPIのインスタンスを作成するだけで、デフォルトでSwagger UIが有効化されます。以下のコードはその基本的な設定例です。

from fastapi import FastAPI

app = FastAPI()

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

このコードを実行することで、自動的にSwagger UIが生成され、/docsエンドポイントからアクセスできるようになります。これにより、開発者は即座にAPIの動作を確認することができます。

FastAPIでSwagger UIを自動生成する手順ガイド

FastAPIでSwagger UIを自動生成する手順はシンプルで、特別な設定を必要としません。以下では、具体的な手順を示しながら、その利便性とカスタマイズ方法について解説します。

FastAPIのインストールとプロジェクト設定

まず、FastAPIをインストールします。pipを使って簡単にインストールでき、以下のコマンドを実行します。

pip install fastapi uvicorn

次に、FastAPIのプロジェクトをセットアップします。新しいPythonファイルを作成し、基本的なFastAPIアプリケーションを設定します。

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

Swagger UIの自動生成機能の有効化方法

FastAPIでは、アプリケーションを作成すると同時にSwagger UIがデフォルトで有効化されます。特別な設定を追加する必要はありません。アプリケーションを実行すると、Swagger UIは自動的に生成され、/docsエンドポイントからアクセスできます。

uvicorn main:app --reload

ブラウザでhttp://127.0.0.1:8000/docsにアクセスすると、Swagger UIが表示されます。

自動生成されたSwagger UIの使い方

自動生成されたSwagger UIでは、APIのエンドポイントやパラメータの詳細を確認できます。エンドポイントに対してテストリクエストを送信し、レスポンスを確認することも可能です。これにより、APIの動作確認が容易になり、開発とテストが効率化されます。

Swagger UIのカスタマイズ方法

Swagger UIの外観や機能はカスタマイズ可能です。例えば、FastAPIのインスタンス作成時に、特定の設定を追加することで、タイトルやバージョン情報を変更できます。

app = FastAPI(
    title="My API",
    description="This is a custom API documentation",
    version="1.0.0"
)

さらに、Swagger UIのテーマやスタイルを変更するための設定も可能で、詳細はSwaggerの公式ドキュメントを参照することで、様々なカスタマイズが行えます。

Swagger UIを用いたFastAPIのドキュメント自動化と活用法

FastAPIとSwagger UIの連携は、APIドキュメントの自動化とその活用において強力なツールとなります。以下に、具体的な活用法とドキュメントの管理方法について説明します。

FastAPIのAPIドキュメントの重要性

APIドキュメントは、開発者やユーザーがAPIを理解し、正しく使用するための重要なリソースです。ドキュメントが整備されていることで、APIの利用者は迅速に必要な情報を得ることができ、開発者はメンテナンスやアップデートの際に効率的に作業を進めることができます。

Swagger UIで生成されるドキュメントの確認方法

Swagger UIを使うことで、生成されたAPIドキュメントを簡単に確認できます。各エンドポイントの詳細、パラメータ、レスポンスの形式が視覚的に表示され、ユーザーは直感的に理解することができます。さらに、ドキュメント内で直接APIリクエストを送信し、動作を確認することも可能です。

ドキュメントを活用したAPIのテスト方法

Swagger UIは、APIのテストツールとしても利用できます。各エンドポイントに対してパラメータを指定し、テストリクエストを送信することで、APIの動作を確認できます。この機能を活用することで、開発中のAPIの挙動を簡単にテストし、不具合を早期に発見することが可能です。

ドキュメントの更新と管理のポイント

APIの変更に伴い、ドキュメントも適宜更新する必要があります。FastAPIでは、コードの変更に応じて自動的にSwagger UIが更新されるため、常に最新のドキュメントを提供することができます。ドキュメントの管理においては、バージョン管理システムを活用し、変更履歴を追跡することが重要です。

FastAPIとSwagger UIの設定とカスタマイズ方法

FastAPIとSwagger UIの設定とカスタマイズは、APIドキュメントの品質を向上させ、特定のニーズに応じた調整を行うために不可欠です。以下に、具体的な設定方法とカスタマイズの手順を示します。

FastAPIの設定ファイルの基本

FastAPIの設定は、環境変数や設定ファイルを使用して行います。例えば、環境ごとに異なる設定を適用するために、.envファイルを使用することが推奨されます。これにより、開発環境と本番環境で異なる設定を簡単に管理できます。

Swagger UIの設定オプションとカスタマイズ

Swagger UIの設定オプションは、FastAPIのインスタンス作成時に指定できます。例えば、Swagger UIのテーマや表示項目を変更するために、以下のように設定します。

app = FastAPI(
    swagger_ui_parameters={
        "defaultModelsExpandDepth": -1,
        "docExpansion": "none"
    }
)

この設定により、デフォルトでモデルが展開されないようにするなど、ユーザーインターフェースをカスタマイズできます。

セキュリティ設定と認証の導入

APIを安全に公開するためには、適切なセキュリティ設定が必要です。FastAPIでは、OAuth2やJWT認証を簡単に導入できます。例えば、OAuth2認証を設定するには、以下のようにします。

from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.get("/users/me")
async def read_users_me(token: str = Depends(oauth2_scheme)):
    return {"token": token}
この設定により、トークンベースの認証を行うことができます。

Swagger UIのデザインカスタマイズ方法

Swagger UIのデザインをカスタマイズすることで、ブランドに合わせた一貫性のあるドキュメントを提供できます。CSSを用いて、色やフォントなどのスタイルを変更することが可能です。カスタムCSSを適用するには、Swagger UIのHTMLテンプレートを修正し、独自のスタイルを追加します。

よくある質問（FAQ）

Swagger UIとは何ですか？

Swagger UI（OpenAPI仕様に基づくドキュメント表示ツール）は、APIのエンドポイント・パラメータ・レスポンス形式をブラウザ上で一覧し、その場でリクエストを送って動作を試せるインターフェースです。FastAPIではOpenAPIスキーマから自動で生成されるため、別途Swaggerの定義ファイルを手書きする必要はありません。

FastAPIのSwagger UIのURLはどこですか？

既定ではSwagger UIが /docs、ReDocが /redoc、両者の元になるOpenAPIスキーマ（JSON）が /openapi.json に公開されます。パスを変更したい場合は FastAPI(docs_url="/api-docs") のように指定します。

本番環境でSwagger UI（/docs）を無効化するには？

FastAPIのインスタンス作成時に docs_url=None と redoc_url=None を指定すると、ドキュメントUIが公開されなくなります。完全に隠さず社内だけに見せたい場合は、UIを残したままBasic認証やOAuth2などのアクセス制御を前段に置く方法もあります。

app = FastAPI(docs_url=None, redoc_url=None)

swagger_ui_parameters では何を設定できますか？

swagger_ui_parameters は、Swagger UI本体へ渡す表示オプションの辞書です。例えば docExpansion（初期展開の状態。none／list／full）、defaultModelsExpandDepth（モデルの展開）、filter（検索ボックスの有効化）などを指定して、UIの初期表示を調整できます。

Swagger UIとReDocはどう違いますか？

どちらもFastAPIが自動生成する同じOpenAPIスキーマを表示しますが、Swagger UI（/docs）はエンドポイントをその場で実行できるインタラクティブ操作に向き、ReDoc（/redoc）は階層的で読みやすい静的なリファレンス閲覧に向いています。用途に応じて使い分けられます。

関連記事

• FastAPIの概要と基本的な特徴：API構築のためのモダンな選択肢
• OpenAPIとは｜Swaggerとの違い・仕様書(YAML/JSON)の書き方とSwagger UIをわかりやすく解説
• Pydantic v2の概要と特徴：V1からの進化点と性能向上
• FastAPIとReactとDockerを使用したフルスタックアプリケーションの構築方法