当サイトは、アフィリエイト広告を利用しています

【FastAPI】Query, Path, Bodyは何のための関数か？

作成日：2026月02月08日

更新日：2026年02月08日

fastapiを使用したREST API実装時にエンドポイントとなる関数の引数で
使われる。

Path
Query
Body

の3つの関数ついて、その目的、構文、使い方をまとめておく。

REST APIや、パスパラメータ、クエリパラメータ、リクエストボディについては下記記事で解説しているので
参照ください

目的～何のための関数か～

この3つは目的は引数の仕様書を作る関数であり

値の取得元を明示
型・制約のバリデーション
OpenAPI（Swagger）用メタデータ定義

の役割がある

当記事では1,2の役割についてメインでまとめる

使い方

実際の使い方や構文、使用する箇所を実行サンプルを使ってまとめていく。

使用箇所

使用箇所は当記事の冒頭でも書いたように、基本的に
エンドポイント関数の引数内で使用される
※その他で単体で使用されることはない。多分。。

実行される場所

APIにリクエスト来た時にに Pydanticが検証で使う ※FastAPIが定義を解析し、Pydanticが実行時に検証する

Query関数

リクエストにクエリパラメータがある場合に
fastapiのエンドポイントの関数で引数として受ける時に使う

用途

クエリパラメータであることを明示
型・制約のバリデーション
OpenAPI（Swagger）用メタデータ定義

Query引数一覧


Query(
    default,
    *,
    alias=None,
    title=None,
    description=None,
    gt=None,
    ge=None,
    lt=None,
    le=None,
    min_length=None,
    max_length=None,
    regex=None,
    deprecated=False,
    example=None,
    examples=None,
    include_in_schema=True
)

Query実装サンプル（標準記法）

Query


from fastapi import Query

@app.get("/items")
def get_item(name: str = Query(...), price: int = Query(0)):
    return {"name": name, "price": price}

「...」（省略不可）で必須になる
Query(0)でデフォルト値指定になる

Query実装サンプル（省略記法）

Query


@app.get("/items")
def get_item(name: str, price: int = 0):  # 直接引数に指定
    return {"name": name, "price": price}

最小限にシンプルに書くこともできる

Path関数

リクエストにパスパラメータがある場合に
fastapiのエンドポイントの関数で引数として受ける時に使う

用途

URLパスの一部であることを明示
必須パラメータのバリデーション
URL設計とAPI仕様の一致保証

Path引数一覧


Path(
    default,
    *,
    alias=None,
    title=None,
    description=None,
    gt=None,
    ge=None,
    lt=None,
    le=None,
    regex=None,
    example=None,
    examples=None,
    deprecated=False,
    include_in_schema=True
)

Path実装サンプル（標準記法）

Path


from fastapi import Path

@app.get("/users/{user_id}")
def get_user(user_id: int = Path(..., description="ユーザーID", ge=1)):
    return {"user_id": user_id}

Path(...)を使うことで、必須指定・説明・バリデーション（例：ge=1）が可能

Path実装サンプル（省略記法）

Path


@app.get("/users/{user_id}")
def get_user(user_id: int):  # 型だけ指定
    return {"user_id": user_id}

型を指定するだけでも動作し、Swagger に型情報が反映される
ただし、説明や制約は追加できない

Body関数

リクエストにbodyがある場合に
fastapiのエンドポイントの関数で引数として受ける時に使う

pydanticのBaseModelクラスと併用することが基本

用途

リクエストボディであることを明示
JSON構造のバリデーション
複数Bodyや単体値を扱うため

Body引数一覧


Body(
    default,
    *,
    embed=False,
    media_type="application/json",
    alias=None,
    title=None,
    description=None,
    example=None,
    examples=None,
    deprecated=False,
    include_in_schema=True
)

Body実装サンプル（標準記法）

Body


from pydantic import BaseModel
from fastapi import Body

class Product(BaseModel):
    name: str
    price: int

@app.post("/products")
def create_product(product: Product = Body(...)):
    return product

必須

Body実装サンプル（省略記法）

Body


@app.post("/products")
def create_product(product: Product):  # Body(...) を省略
    return product

省略した場合は必須になる。

実務で使うための補足事項

embed

下記記事で記載

- embedについて

オプショナルにしたい

Noneを受けれるオプショナルにしたい場合は

型 → Noneを許可
デフォルト値　→ Noneを許可

にする必要がある。

Queryで書く場合

Queryでoptional


async def get_users(
    age: int | None = Query(None, description="ユーザーの年齢でフィルタ")
):

型でintとNoneを許可
デフォルトでNoneを設定

データモデルで書く場合

データモデル


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

フィールド単位でオプショナル化

デフォルト値と必須の設定の注意

...の場合は必須

必須


Query(...)
Path(...)
Body(...)

デフォルト値があると場合は任意

任意


Query(1)

class UserCreate(BaseModel):
    name: str          # 必須
    age: int | None    # 任意

Pathの特殊ルール


@app.get("/users/{user_id}")
def get_user(user_id: int):

Path パラメータは暗黙的に必須
Path(...) を書かなくても必須

間違い


q: str = None  # 型が None を許可していない

depends(再利用)

エンドポイントの引数を作るために、先に関数を実行する仕組み

かみ砕くと

Depends は「引数定義ごと再利用する」仕組み
FastAPIはまずDepends 指定された関数を実行し、その戻り値をエンドポイント関数の引数として注入する
関数の戻り値がそのまま引数になる

を行う

depends


def common_query(
    q: str | None = Query(None, min_length=1, max_length=50)
):
    return q

@app.get("/items")
def read_items(q: str = Depends(common_query)):
    ...

流れは

リクエストがくる
その値を引数として、common_query関数が呼ばれる
common_queryが実行（バリデーション）される
エラーなければcommon_queryが引数qをreturn
エンドポイントread_itemsの引数 q に注入される
read_items が実行される

になる

まとめ

fastapiでよく見る

Path
Query
Body

について詳しく調べたみた。
この前提を持った上で、

を見れば理解が深まると思う