fastapi

FastAPI

このスキルでは、FastAPI を使った API の構築について包括的に説明します。

クイックナビゲーション

トピック	リファレンス
はじめに	references/first-steps.md
パスパラメーター	references/path-parameters.md
クエリパラメーター	references/query-parameters.md
リクエストボディ	references/request-body.md
バリデーション	references/validation.md
ボディの応用	references/body-advanced.md
Cookie／ヘッダー	references/cookies-headers.md
Pydantic モデル	references/models.md
フォーム／ファイル	references/forms-files.md
エラー処理	references/error-handling.md
パス設定	references/path-config.md
依存関係	references/dependencies.md
セキュリティ	references/security.md
ミドルウェア	references/middleware.md
CORS	references/cors.md
データベース	references/sql-databases.md
プロジェクト構成	references/bigger-applications.md
バックグラウンドタスク	references/background-tasks.md
メタデータ／ドキュメント	references/metadata-docs.md
テスト	references/testing.md
高度なレスポンス	references/responses-advanced.md
WebSocket	references/websockets.md
テンプレート	references/templates.md
設定／環境変数	references/settings.md
ライフスパンイベント	references/lifespan.md
OpenAPI の応用	references/openapi-advanced.md

使用する場面

• Python で REST API を作成する
• 自動バリデーション付きのエンドポイントを追加する
• OAuth2／JWT 認証を実装する
• Pydantic モデルを使用する
• 依存性注入を追加する
• CORS、ミドルウェアを設定する
• ファイルをアップロードし、フォームを処理する
• API エンドポイントをテストする

インストール

Python 3.10 以降が必要です。pip install "fastapi[standard]"（uvicorn を含むフル版）または pip install fastapi（最小版）でインストールします。フォーム／ファイルを扱う場合は python-multipart を追加してください。

リリースの主な変更点（0.139.2 → 0.141.1）

• フロントエンドの開発体験（0.141.0）：app.frontend() の check_dir は、デフォルトで "auto" になりました。FASTAPI_ENV=development の場合は警告を出してフロントエンドディレクトリの存在確認を省略し、それ以外の場合は存在を必須とします。fastapi dev は、すでに設定されていない限り FASTAPI_ENV=development を自動的に設定するため、フロントエンドのビルド前に開発サーバーを実行してもエラーが発生しなくなりました。
• フロントエンドの修正（0.141.1）：フロントエンドのルートで使用される依存関係が生成するバックグラウンドタスクとレスポンスヘッダーが、黙って破棄されずに正しく適用されるようになりました（依存関係のサポートは 0.139.0 で追加）。FASTAPI_ENV が FastAPI CLI ガイドに記載されました。
• 依存性注入のメモリーリファクタリング（0.140.0 ～ 0.140.7）：大規模なアプリケーションでのメモリー使用量を削減するため、OpenAPI 生成、リクエストパラメーターの解決、ボディフィールドの処理において、内部の依存関係ツリーを繰り返しフラット化しなくなりました。また、依存関係の解決に使われる内部の lru_cache の上限が、大規模なアプリケーションに対応できるよう引き上げられました。これは内部的な最適化であり、コードの変更は必要ありません。
• ストリーミングの修正（0.140.8 ～ 0.140.13）：include_router() が、ネストされたルーターの yield ベースのエンドポイントで宣言されたストリームの項目型を保持するようになりました。response_model_exclude などの response_model_* パラメーターが、yield ベースのエンドポイントだけでなく、Iterable[Model] を return する通常の（ジェネレーターではない）エンドポイントでも適用されるようになりました。SSE／JSONL ストリーミングエンドポイントで設定した status_code が常に 200 になるのではなく、正しく適用されるようになりました。fastapi.sse 専用の API リファレンスページが追加されました。
• jsonable_encoder の修正（0.140.9）：exclude_defaults がトップレベルのモデルフィールドだけでなく、辞書のキーと値にも適用されるようになりました。

リリースの主な変更点（0.137.0 → 0.139.2）

• フロントエンドの配信（0.138.0）：app.frontend("/", directory="dist") で、ビルド済みの静的フロントエンドを FastAPI アプリから直接配信できるようになりました。0.139.0 では app.frontend() に依存関係のサポートが追加され、フロントエンドでの Cookie 認証が自動化されました。また、0.139.1 では /users/john.doe のようなドットを含むパスのフォールバックが修正されました。
• ルーターの内部処理（0.137.0）：include_router() がルートを複製せず、APIRouter／APIRoute のインスタンスを保持するようになりました。そのため、インクルード後に追加されたルートが自動的に反映され、メモリー使用量も減少します。カスタムの APIRouter／APIRoute サブクラスでは、高度なルーティング向けに .matches()／.handle()（アルファ版）が利用できるようになりました。
• スレッドセーフティ（0.139.2）：ルートの構築がスレッドセーフになるようリファクタリングされました。主に、並列スレッドで実行するテストに関係する変更です。

リリースの主な変更点（0.133.0 → 0.136.1）

• 0.134.0： yield を使用した JSON Lines のストリーミングとバイナリデータのストリーミングをサポートしました。
• 0.135.0： Server-Sent Events（SSE）を正式にサポートしました（EventSourceResponse）。
• 0.135.1： リクエストの非同期 exit stack における TaskGroup の使用に関する問題を修正しました（安定性の修正）。
• 0.136.1： 非推奨機能を避けるため、FastAPI の Pydantic v2 コードを更新し、Starlette を 1.0.0 に引き上げました。

パッチノート（0.136.2 → 0.136.3）

• SSE レスポンスでイベントフィールドの検証がより厳密になりました。形式が不正な ServerSentEvent ペイロードは、不正なフレームが黙ってストリーミングされるのではなく、より早い段階でエラーになります。
• convert_underscores=True（デフォルト）の場合、ヘッダーパラメーターがアンダースコアを含む名前の受信ヘッダーを受け入れなくなりました。クライアントがアンダースコア付きヘッダーを実際に送信する場合は、Header(convert_underscores=False) を宣言し、プロキシチェーンでそのヘッダーが許可されていることを確認してください。

クイックスタート

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

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

実行：fastapi dev main.py

基本パターン

型安全なパラメーター

from typing import Annotated
from fastapi import Path, Query

@app.get("/items/{item_id}")
def read_item(
    item_id: Annotated[int, Path(ge=1)],
    q: Annotated[str | None, Query(max_length=50)] = None
):
    return {"item_id": item_id, "q": q}

検証付きリクエストボディ

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)

@app.post("/items/", response_model=Item)
def create_item(item: Item):
    return item

依存関係

from fastapi import Depends

async def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.get("/users/")
def list_users(db: Annotated[Session, Depends(get_db)]):
    return db.query(User).all()

認証

from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]):
    return decode_token(token)

@app.get("/users/me")
def read_me(user: Annotated[User, Depends(get_current_user)]):
    return user

API ドキュメント

• Swagger UI：/docs
• ReDoc：/redoc
• OpenAPI：/openapi.json

ベストプラクティス

• パラメーターには Annotated[Type, ...] を使用します
• リクエストとレスポンスには Pydantic モデルを定義します
• 出力のフィルタリングには response_model を使用します
• 適切な HTTP ステータスコードを設定するため、status_code を追加します
• API を整理するため、tags を使用します
• 認証のため、ルーターまたはアプリのレベルで dependencies を追加します

禁止事項

• ❌ データベースモデルをそのまま返さないでください（レスポンスモデルを使用します）
• ❌ パスワードを平文で保存しないでください（bcrypt/passlib を使用します）
• ❌ 同じエンドポイントで Body と Form/File を併用しないでください
• ❌ 非同期エンドポイントで同期的なブロッキング I/O を使用しないでください
• ❌ エラー処理で HTTPException を省略しないでください

リンク

• ドキュメント
• リリース
• GitHub
• PyPI