FastAPIの自動Swagger UIをカスタマイズ！タイトル変更から認証追加まで完全ガイド
こんにちは。テックリードの皆さん、日々のAPI開発スピードに満足していますか？
FastAPIの最大の魅力の一つは、コードを書くだけで自動生成されるインタラクティブなAPIドキュメント（Swagger UI / ReDoc）です。しかし、デフォルトのまま本番運用したり、チームメンバーに共有したりしていませんか？「タイトルが `FastAPI` のままでダサい」「JWT認証のテストをするたびにトークンを入力し直すのが苦痛」「クライアントサイドのエンジニアから『どのエンドポイントが認証必須なのか分からない』とクレームが来る」。
これらはすべて、FastAPIの標準機能とOpenAPIスキーマの正しいハック方法を知ることで、一瞬で解決できます。
今回は、単なる公式ドキュメントのなぞりではありません。現場の生産性を極限まで高め、チーム開発のストレスをゼロにするための「Swagger UI実戦カスタマイズの極意」を叩き込みます。
—
1. FastAPI標準のSwagger UIの魅力と限界
FastAPIは、内部でPydanticとStarletteをベースにしながら、OAS（OpenAPI Specification）に準拠したスキーマを自動生成します。これが「コードファーストでありながら、最高峰のドキュメントが手に入る」と言われる理由です。
デフォルトの限界
1. ブランディングの欠如: プロジェクト名が反映されず、`FastAPI` という汎用的なタイトルが表示される。
2. 認証フローの不親切さ: JWT（Bearer Token）を使っている場合、デフォルトのままだとSwagger UI上で「どこにどうトークンを入れたらいいか」が直感的に伝わらない。
3. メタ情報の不足: バージョン管理、利用規約、連絡先などのメタデータがないと、マイクロサービス環境でどのAPIを叩いているのか混乱する。
これらを解消し、「開いた瞬間に誰もが迷わずテストできるドキュメント」へと昇華させましょう。
—
2. app初期化時のタイトルやdescription、versionの設定方法
まずは基本の基ですが、ここを疎かにしているプロジェクトが多すぎます。メタデータは単なる「飾り」ではなく、自動生成されるクライアントSDKやAPIゲートウェイにとっても重要な情報源です。
以下のコードは、実務で即座に使えるプロダクションレディな `main.py` の初期化設定です。Markdownを活用して、ドキュメントの見た目をリッチにするのがプロの技です。
main.py
from fastapi import FastAPI
APIドキュメントにリッチな説明（Markdown対応）を記述するための定数
DESCRIPTION = “””
次世代ECプラットフォームのコアAPI群です。 🚀
認証
すべての保護されたエンドポイントには、`Authorization: Bearer
エラーハンドリング
共通のエラーフォーマットについては、[Wiki](https://internal.wiki.example.com/api/errors)を参照してください。
“””
app = FastAPI(
title=”Nexus Commerce Core API”,
description=DESCRIPTION,
version=”2.4.1″,
terms_of_service=”https://example.com/terms/”,
contact={
“name”: “API Platform Team”,
“url”: “https://github.com/orgs/example/teams/api-platform”,
“email”: “api-platform@example.com”,
},
license_info={
“name”: “Proprietary”,
“url”: “https://example.com/licenses/PROPRIETARY”,
},
# 本番環境ではドキュメントパスを隠すなどの制御も可能
docs_url=”/docs”,
redoc_url=”/redoc”,
openapi_url=”/openapi.json”,
)
💡 テックリードの知見：メタデータ管理のベストプラクティス
バージョンやタイトルをコードにハードコーディングせず、環境変数（Pydanticの `BaseSettings` など）や `pyproject.toml` から動的に読み込む設計にしておくと、CI/CDパイプラインでのバージョンインクリメントが劇的に楽になります。
—
3. OpenAPIスキーマを直接ハックしてBearer認証（JWT）のロックアイコンを有効化する手順
ここからが本題です。FastAPIのデフォルト機能だけでは、Swagger UIの右上に「Authorize」ボタンを出してJWT認証をインタラクティブにテストさせる設定がやや直感的ではありません。
OpenAPIスキーマ（JSON）を直接カスタマイズ（ハック）し、「鍵（Lock）アイコン」をビシッと鎮座させ、一度トークンを入力すれば全リクエストにそれが自動付与される状態を作り上げます。
実装コード：カスタムOpenAPIジェネレータ
security.py または main.py
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
def custom_openapi(app: FastAPI):
“””
FastAPIのデフォルトOpenAPIスキーマをオーバーライドし、
OAuth2 / Bearer JWTのセキュリティスキームを強制追加する。
“””
if app.openapi_schema:
return app.openapi_schema
# 基本のスキーマを生成
openapi_schema = get_openapi(
title=app.title,
version=app.version,
description=app.description,
routes=app.routes,
)
# securitySchemesの定義を追加（Bearer JWT）
if “components” not in openapi_schema:
openapi_schema[“components”] = {}
openapi_schema[“components”][“securitySchemes”] = {
“OAuth2Bearer”: {
“type”: “http”,
“scheme”: “bearer”,
“bearerFormat”: “JWT”,
“description”: “JWTアクセストークンを入力してください（例: `eyJhbGciOi…`）”,
}
}
# グローバルセキュリティとして適用する場合（全エンドポイントにロックアイコンを付与）
# ※特定の公開APIがある場合は、個別のrouterで security=[] を指定して除外してください
openapi_schema[“security”] = [{“OAuth2Bearer”: []}]
app.openapi_schema = openapi_schema
return app.openapi_schema
FastAPIアプリへの適用
app = FastAPI()
app.openapi = lambda: custom_openapi(app)
これを行うことで、Swagger UIの画面右上に「Authorize」ボタンが現れ、トークンを入力すると、以降のすべてのリクエストヘッダーに `Authorization: Bearer
—
🚀 プロの現場で差をつける！実践テクニックと環境共有
ここからは、チーム全体の開発スピードをさらに引き上げるための「現場の隠し味」をいくつか授けましょう。
1. 開発効率を爆上げするSwagger UIのキーボードショートカット
ブラウザでSwagger UIを開いているとき、以下のテクニックを知っているだけで操作スピードが倍になります。
- エンドポイントの一括展開/折りたたみ: `Ctrl + Click` (Macは `Cmd + Click`) でタグ単位の開閉をコントロール。
- 素早いフォーカス: `Tab` キーを駆使してリクエストボディのJSONエディタへ素早く移動。
2. CDNや外部CSS/JSを用いたデザインのカスタマイズ
デフォルトのSwagger UIのデザインを社内ブランドカラーに合わせたい場合や、CDN経由でカスタムCSSを読み込ませたい場合は、FastAPIの `get_swagger_ui_html` をオーバーライドします。
from fastapi.responses import HTMLResponse
from fastapi.openapi.docs import get_swagger_ui_html
@app.get(“/docs”, include_in_schema=False)
async def custom_swagger_ui_html():
return get_swagger_ui_html(
openapi_url=app.openapi_url,
title=f”{app.title} – Swagger UI”,
oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
# 社内CDNや独自CSSの適用例
swagger_js_url=”https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js”,
swagger_css_url=”https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css”,
# ファビコンの変更
swagger_favicon_url=”https://example.com/favicon.ico”,
)
3. チーム開発における設定の共有化ルール
APIのスキーマ変更は、クライアントサイド（Web/Mobile）の開発者に即座に共有されなければなりません。CI/CDパイプライン（GitHub Actionsなど）で、テスト実行時に自動で `openapi.json` をファイルとして吐き出し、Artifactとして保存、あるいはモックサーバー（PrismやStoplightなど）へ自動同期する仕組みを構築しましょう。
.github/workflows/api-schema.yml の抜粋例
name: Export OpenAPI Schema
on:
push:
branches: [ main ]
jobs:
export:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: ‘3.11’
- name: Install dependencies
run: pip install poetry && poetry install
- name: Generate openapi.json
run: poetry run python scripts/export_openapi.py
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: openapi-schema
path: openapi.json
—
まとめ
FastAPIの自動ドキュメント生成は、ただの「おまけ機能」ではありません。チーム全体の開発体験（DX）を左右する最重要インターフェースです。
- タイトル、バージョン、リッチなMarkdown説明で文脈を伝える。
- OpenAPIスキーマハックでBearer認証のロックアイコンを有効化し、テストのストレスを消し去る。
- CI/CDと連携してスキーマを常に最新に保つ。
これらの実装をプロジェクトに組み込むことで、API開発のスピードと品質は次元の違うレベルへと到達します。さあ、今すぐあなたのコードベースの `main.py` を書き換えに行きましょう。