こんにちは！API開発の世界へようこそ。
PythonでWeb APIを作るなら、今やFastAPIは第一選択肢と言っても過言ではありません。その最大の発明であり、僕たちエンジニアを虜にしてやまないのが「コードを書くだけで、勝手に美しいインタラクティブなAPIドキュメント（Swagger UI）が生成される」という体験ですよね。
しかし、開発が進んでチームメンバーが増えたり、フロントエンドエンジニアにAPIを共有したり、あるいはクライアントに納品する段階になると、こんな壁にぶつかりませんか？
- 「タイトルがデフォルトの『FastAPI』のままで素人っぽい…」
- 「どのAPIが認証が必要で、どれが不要なのかわからない」
- 「JWT（Bearerトークン）を使った認証のテストを、Swagger UI上の『鍵マーク（Authorizeボタン）』からスマートに行いたい」
大丈夫です！これをマスターすれば、毎日の開発作業が劇的に楽になりますし、何より「プロが作った使いやすいAPIドキュメント」へと一瞬で進化させることができます。
今回は、FastAPIの自動Swagger UIをベースに、タイトルや説明文のカスタマイズといった基本から、OpenAPIスキーマを直接拡張してJWT（Bearer）認証のロックアイコンを有効化するプロのテクニックまで、丁寧にわかりやすく解説していきますね。
—
1. FastAPI標準のSwagger UI――その圧倒的魅力と「現場での限界」
まずは、FastAPIとSwagger UIの関係性について簡単に整理しておきましょう。
自動生成の魔法とその仕組み
FastAPIは、Pythonの型ヒント（Type Hints）とPydanticというデータ検証ライブラリを極限まで活用しています。関数に型を書くだけで、裏側でOpenAPI（旧Swagger）と呼ばれる「APIの設計図（JSON/YAML）」をリアルタイムに自動生成しているのです。
そして、その設計図をブラウザ上で視覚的に操作できるようにしてくれるWeb UIがSwagger UI（標準では `/docs` でアクセス可能）です。
[ FastAPI Code ] ──(型ヒントから自動生成)──> [ OpenAPI Schema (JSON) ] ──(描画)──> [ Swagger UI ]
なぜデフォルトのままではダメなのか？（現場での限界）
FastAPIをインストールして初期状態のまま立ち上げると、非常にシンプルで魅力的な画面が表示されます。しかし、実際のプロジェクトでは以下のような問題が発生します。
1. メタデータの欠落: APIのタイトルが `FastAPI` になり、バージョンも `0.1.0` のまま。どのようなシステムなのか、誰が保守しているのかが伝わりません。
2. 仕様の不透明さ: エンドポイントごとの説明や、レスポンスの構造、利用可能なタグ（カテゴリ分け）が整理されていないと、フロントエンド開発者がソースコードを読み解く羽目になります。
3. 認証テストのやりづらさ: JWT認証などを導入した際、Swagger UI上でトークンをセットしてリクエストを試す「Authorizeボタン（ロックアイコン）」がないと、毎回PostmanやcURLを立ち上げる必要が出てきます。
「ドキュメントはAPIの顔」です。ここを少し整えるだけで、チームの開発効率は何倍にも跳ね上がりますよ。
—
2. app初期化時のメタデータ設定方法
それでは、実践に入っていきましょう！まずは最も簡単で、効果が絶大な `FastAPI()` の初期化引数を使ったカスタマイズです。
必要なパッケージの準備
まずは必要なライブラリをインストールします。環境が手元にある方は、新しく仮想環境を作って試してみてください。
pip install fastapi uvicorn
コードで見るメタデータの設定
FastAPIのインスタンスを生成する際に、`title`、`description`、`version`、`terms_of_service`、`contact`、`license_info` などの引数を渡すことができます。`description` にはMarkdown記法が使えるのが嬉しいポイントです！
以下のコードを `main.py` として保存してみましょう。
main.py
from fastapi import FastAPI, status
from pydantic import BaseModel
Markdown形式で詳細なドキュメントを記述
description = “””
🚀 プロダクト管理API へようこそ！
このAPIは、自社ECサイトのプロダクト情報を管理するためのバックエンドサービスです。
主な機能
- Products: 商品の検索、取得、作成、更新、削除（CRUD）
- Users: ユーザー情報の管理（※今後実装予定）
—
開発チームへのお問い合わせは [社内Slack #api-dev] までお願いします。
“””
FastAPIの初期化時にメタデータを余すことなく設定する
app = FastAPI(
title=”EC Product Management API”,
description=description,
version=”1.0.0″,
terms_of_service=”https://example.com/terms/”,
contact={
“name”: “APIサポートチーム”,
“url”: “https://example.com/support”,
“email”: “support@example.com”,
},
license_info={
“name”: “Apache 2.0”,
“url”: “https://www.apache.org/licenses/LICENSE-2.0.html”,
},
# タグの順序や説明を定義してドキュメントを整理する
openapi_tags=[
{
“name”: “products”,
“description”: “商品データに関する操作を行うエンドポイント群です。”,
},
{
“name”: “system”,
“description”: “ヘルスチェックやシステム状態を取得するエンドポイントです。”,
},
],
)
レスポンスモデルの定義
class HealthCheck(BaseModel):
status: str = “ok”
エンドポイントの定義（tagsを指定してグループ化）
@app.get(
“/health”,
response_model=HealthCheck,
tags=[“system”],
summary=”システムヘルスチェック”,
description=”サーバーが正常に稼働しているかを確認するための軽量なエンドポイントです。”
)
def health_check():
“””
関数内のDocstringも、FastAPIは自動的に読み取って
Swagger UIの詳細説明として表示してくれます！
“””
return {“status”: “ok”}
if __name__ == “__main__”:
import uvicorn
# サーバーの起動
uvicorn.run(“main:app”, host=”127.0.0.1″, port=8000, reload=True)
動作確認手順
ターミナルで実行してみましょう。
python main.py
サーバーが起動したら、ブラウザで `http://127.0.0.1:8000/docs` にアクセスしてみてください。
どうでしょうか？デフォルトの殺風景な画面から一変し、プロフェッショナルで美しいドキュメントが表示されたはずです！
タイトルが明確になり、Markdownで書いた説明文が読みやすく配置され、`system` タグでエンドポイントが綺麗にグループ化されていますね。
—
3. OpenAPIスキーマをハックしてBearer認証（JWT）のロックアイコンを有効化する
ここからが本題であり、現場で一番重宝される「プロの極意」です！
Web APIの開発では、ヘッダーに `Authorization: Bearer
Swagger UIの上部に「Authorize 🔓」というボタンを配置し、そこにトークンを一度入力すれば、すべてのテストリクエストに自動でトークンを付与してくれる仕組みを作ってみましょう。
FastAPI標準の `HTTPBearer` とカスタムスキーマ構築
FastAPIには `fastapi.security` モジュール内に `HTTPBearer` という便利なセキュリティクラスが用意されています。これを使用することで、自動的にOpenAPIの認証定義（Security Schemes）を構築できます。
さらに今回は、「OpenAPIスキーマのカスタマイズ（`app.openapi()` のオーバーライド）」の書き方も合わせて伝授します。これを知っておくと、どんな特殊な認証ヘッダーやSwagger UIのカスタム要求にも柔軟に対応できるようになりますよ！
それでは、完全版のコードを見てみましょう。
main_auth.py
from typing import Any, Dict
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from fastapi.openapi.utils import get_openapi
from pydantic import BaseModel
app = FastAPI(
title=”認証付き セキュアAPI”,
description=”JWT Bearer認証を組み込んだWeb APIのサンプルです。”,
version=”1.1.0″,
)
1. Bearer認証のセキュリティスキームを定義
bearerFormat=”JWT” と指定することで、UI上に「JWT」のフォーマットヒントが表示されます
security_scheme = HTTPBearer(bearerFormat=”JWT”, auto_error=False)
2. トークンを検証する依存関係（Dependency）関数
def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(security_scheme)):
“””
リクエストヘッダーから Authorization: Bearer
“””
if not credentials:
# ヘッダーが存在しない、または形式が不正な場合
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail=”認証ヘッダー（Bearerトークン）が必要です。”,
headers={“WWW-Authenticate”: “Bearer”},
)
token = credentials.credentials
# 💡 実際のプロダクトではここで PyJWT などを使ってトークンをデコード・検証します
# 今回はデモ用に ‘secret-token-123’ を正解とします
if token != “secret-token-123″:
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail=”トークンが無効または期限切れです。”,
)
# 検証成功時、ユーザー情報を返す
return {“user_id”: 42, “username”: “legend_engineer”}
— エンドポイント定義 —
@app.get(“/”, summary=”パブリックエンドポイント”)
def public_endpoint():
“””誰でもアクセスできる公開エンドポイントです。”””
return {“message”: “これは公開情報です。誰でも閲覧可能です。”}
@app.get(“/secure-data”, summary=”保護されたエンドポイント”)
def secure_endpoint(current_user: dict = Depends(get_current_user)):
“””
認証が必要なエンドポイントです。
Swagger UIの「Authorize」ボタンからトークンを設定してテストできます。
“””
return {
“message”: “認証に成功しました！機密データへアクセスできます。”,
“user_info”: current_user
}
3. OpenAPIスキーマの直接カスタムハック（キャッシュ戦略付き）
def custom_openapi() -> Dict[str, Any]:
# すでに生成済みのスキーマ（キャッシュ）があればそれを返す
if app.openapi_schema:
return app.openapi_schema
# FastAPIのデフォルトOpenAPIスキーマを取得
openapi_schema = get_openapi(
title=app.title,
version=app.version,
description=app.description,
routes=app.routes,
)
# セキュリティスキームの明示的な定義を追加・補正したい場合
# (HTTPBearerを使っていれば基本自動で生成されますが、さらに拡張したい時のハック手法です)
if “components” not in openapi_schema:
openapi_schema[“components”] = {}
# OpenAPI 3.0 の仕様に従って Security Schemes を設定
openapi_schema[“components”][“securitySchemes”] = {
“HTTPBearer”: {
“type”: “http”,
“scheme”: “bearer”,
“bearerFormat”: “JWT”,
“description”: “フォームにJWTトークンを入力してください（例: secret-token-123）”
}
}
# キャッシュに保存して再利用
app.openapi_schema = openapi_schema
return app.openapi_schema
カスタム関数をFastAPIアプリのopenapiメソッドに上書き割り当て
app.openapi = custom_openapi
if __name__ == “__main__”:
import uvicorn
uvicorn.run(“main_auth:app”, host=”127.0.0.1″, port=8000, reload=True)
Swagger UIでの認証テスト手順（画面でどう見えるか？）
コードを実行し、ブラウザで `/docs` を開いてみてください。
1. 「Authorize 🔓」ボタンの出現: 画面右上に緑色の `Authorize 🔓` ボタンが表示されます！また、`/secure-data` エンドポイントの横にも小さな鍵マークが現れます。
2. トークンの入力: `Authorize` ボタンをクリックするとダイアログが表示されます。`Value` の入力欄にテスト用のトークン `secret-token-123` を入力し、`Authorize` をクリックしてダイアログを閉じます。鍵マークが閉じられた状態（🔒）に変わります。
3. リクエストのテスト:
- `/secure-data` を開き、`Try it out` ➔ `Execute` を押します。
- レスポンスとして `200 OK` とユーザー情報が返ってくることを確認してください！
- 送信されたリクエストヘッダーを見ると、`Authorization: Bearer secret-token-123` が自動付与されていることが確認できます。
4. 失敗テスト: `Authorize` ダイアログで一度 `Logout` し、適当なダメなトークン（例: `bad-token`）を入力して再度実行してみてください。しっかり `403 Forbidden` エラーが返ってくるはずです。
この「画面上で鍵を解錠して認証テストができる」環境があるだけで、APIのテスト速度と信頼性は桁違いに上がります。
—
4. まとめ＆一歩先を目指すあなたへ
お疲れ様でした！今回はFastAPIにおけるSwagger UIのカスタマイズについて、基礎から実践的な認証の統合までを一気に駆け抜けました。
今回のポイントを復習しましょう。
1. `FastAPI()` 初期化設定: `title` や `description`（Markdown対応）、`version`、`tags` を設定することで、APIドキュメントとしての視認性と品質が激変する。
2. `HTTPBearer` と `Depends`: 認証ロジックを依存関係として切り出すことで、綺麗なコードと正確なOpenAPI定義が両立できる。
3. `custom_openapi()` のハック: FastAPIが生成するスキーマ辞書を直接操作することで、どんな複雑なセキュリティ要件やOpenAPI拡張仕様にも柔軟に対応できる。
さらなる高みへ（一歩先のアドバイス）
もし本番環境（Production）でAPIを運用する場合は、セキュリティの観点から「本番環境では `/docs` や `/redoc` を非表示にする」というテクニックも知っておくと役立ちます。
import os
環境変数に応じてドキュメントを無効化する
is_production = os.getenv(“ENV”) == “production”
app = FastAPI(
title=”My API”,
docs_url=None if is_production else “/docs”, # 本番では Swagger UI を無効化
redoc_url=None if is_production else “/redoc”, # 本番では ReDoc を無効化
openapi_url=None if is_production else “/openapi.json” # スキーマJSONも隠す
)
開発環境では親切で使いやすい最高レベルのドキュメントを提供し、本番環境では不要な情報漏洩を防ぎしっかりとガードを固める。これができるエンジニアは、現場でも非常に重宝されます。
FastAPIの魅力は、ただ速いだけでなく「開発者の体験（Developer Experience）」を極限まで高めてくれることにあります。
今回学んだ知識を活かして、ぜひチームメンバーやクライアントが感動するような最高のAPIを作り上げてみてくださいね！
何か分からないことがあれば、いつでも聞いてください。応援しています！