FastAPIにおけるPydanticの役割

FastAPIを学び始めると、ほぼ必ず登場するのが Pydantic です。

from pydantic import BaseModel

この一行を何度も書くものの、

「FastAPIとPydanticの役割分担がよく分からない」
「結局、何をしてくれているライブラリなの？」

と感じる人は多いはずです。

この記事では、FastAPIにおけるPydanticの役割を

なぜ必要なのか
何を自動でやってくれているのか
FastAPIとどう協調しているのか

という観点で、簡単にまとめてみます。

Contents

Pydanticの役割
Pydanticが無いと何が困る？
- Pydanticなしの世界
- Pydanticありの世界
FastAPI × Pydantic の基本構造
①リクエストボディのバリデーション
- 実行時の流れ
②型変換（パース）を自動でやってくれる
③レスポンスモデルとしても使える
- 何が起きる？
④OpenAPI（Swagger）の自動生成
⑤FastAPIがPydanticを「どう使っているか」
⑥なぜ「Pydanticモデル＝設計書」になるのか
まとめ

Pydanticの役割

まず一言で言うと、

Pydanticは「Pythonの型定義を使って、APIの入出力を検証・変換・説明してくれるライブラリ」

です。

FastAPIは、

HTTPリクエストを受け取る
ルーティングする
レスポンスを返す

という Webフレームワーク。

一方で Pydantic は、

リクエストデータが正しいかチェック
型変換（文字列 → int / datetime など）
API仕様（OpenAPI）の自動生成

を担当します。

FastAPIは「流れ」を作り、Pydanticは「中身の正しさ」を保証する、という関係です。

Pydanticが無いと何が困る？

例えば、次のようなJSONを受け取るAPIを考えます。

{
  "id": "123",
  "name": "Alice",
  "age": "20"
}

Pydanticなしの世界

id は本当は int にしたい
age も int のはず
欠けている項目があったらエラーにしたい

これを全部 自分で if 文でチェック すると…

if not isinstance(id, int):
    raise ValueError(...)

地獄です。

Pydanticありの世界

class User(BaseModel):
    id: int
    name: str
    age: int

これだけで、

型チェック
型変換（”123″ → 123）
エラーメッセージ生成

を 自動で やってくれます。

FastAPI × Pydantic の基本構造

最も基本的な例を見てみます。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str

@app.post("/users")
async def create_user(user: User):
    return user

ここで起きていることを分解します。

①リクエストボディのバリデーション

async def create_user(user: User):

この user: User を見て FastAPI はこう判断します。

「このエンドポイントは、User 形式のJSONを body で受け取る」

実行時の流れ

クライアントがJSONを送る
FastAPIがそれをPydanticに渡す
Pydanticが以下を実施

必須項目があるか
型が合っているか
変換できるか

問題なければ User インスタンスを生成
問題があれば 422 Unprocessable Entity を返す

バリデーション処理は一切書いていない のがポイントです。

②型変換（パース）を自動でやってくれる

Pydanticは「型変換」がとても賢いです。

class Event(BaseModel):
    start_at: datetime

{
  "start_at": "2025-01-01T10:00:00"
}

これを送ると、

文字列 → datetime に自動変換

されます。

APIの境界で型が保証される のが超重要です。

③レスポンスモデルとしても使える

Pydanticは「入力」だけでなく「出力」も管理できます。

class UserOut(BaseModel):
    id: int
    name: str

@app.get("/users/{user_id}", response_model=UserOut)
async def get_user(user_id: int):
    return {
        "id": user_id,
        "name": "Alice",
        "password": "secret"  # ← 返らない
    }

何が起きる？

response_model に指定したフィールドだけ返却
余計なデータは自動で削除
型チェックも実施

セキュリティ事故防止にも直結 します。

④OpenAPI（Swagger）の自動生成

FastAPIが /docs を自動で提供できる理由の一つが Pydantic です。

Pydanticモデルから、

フィールド名
型
必須 / 任意
説明文

を読み取り、OpenAPI仕様を生成します。

class User(BaseModel):
    id: int
    name: str
    age: int | None = None

これだけで、Swagger UI に

必須 / 任意
型

が正確に表示されます。

ドキュメントを書かなくても仕様が伝わる のが強みです。

⑤FastAPIがPydanticを「どう使っているか」

整理すると役割分担はこうです。

役割	担当
HTTP処理	FastAPI
ルーティング	FastAPI
バリデーション	Pydantic
型変換	Pydantic
スキーマ定義	Pydantic
OpenAPI生成	FastAPI + Pydantic

FastAPIは

「型ヒントを最大限活用する設計」

になっており、その中核がPydanticです。

⑥なぜ「Pydanticモデル＝設計書」になるのか

Pydanticモデルは、

実行時のチェック
API仕様書
チーム内の共通理解

を 1つのコード で兼ねています。

class Order(BaseModel):
    order_id: int
    amount: float
    created_at: datetime

これはそのまま、

APIの入力仕様
出力仕様
データモデルの説明

になります。

コード＝ドキュメント という状態を作れるのが最大の価値です。

まとめ

FastAPIにおけるPydanticの役割を一言でまとめると、APIの入出力を安全・正確・分かりやすくするための中核ライブラリです。

リクエストのバリデーション
型変換（パース）
レスポンス制御
OpenAPI自動生成

を ほぼ設定なしで 提供してくれます。