FastAPI パスパラメータ数値検証

クエリパラメータとの使用Query検証を追加する方法は同じです。次を使用できますPathパスパラメータに数値検証とメタデータを宣言します。


Path をインポート

からfastapiインポートPath、からtypingインポートAnnotated:

例

from typing import Annotated
from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    # パスパラメータにメタデータと検証を追加
    item_id: Annotated[int, Path(title="商品ID", description="取得する商品ID", ge=1)],
):
    return {"item_id": item_id}

パスパラメータは常に必須です。URLパスの一部でなければならないためです。デフォルト値を宣言しても、必須パラメータとして扱われます。


数値検証

PathとQuery以下はすべて数値検証パラメータをサポートしています:

パラメータ意味英語由来
gtより大きいgreater than
ge以上greater than or equal
ltより小さいless than
le以下less than or equal

以上(ge)

制限item_id>= 1 である必要があります:

例

from typing import Annotated
from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(ge=1)],  # item_id は >= 1 である必要があります
):
    return {"item_id": item_id}

数値検証の組み合わせ

例

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    # item_id は > 0 かつ <= 1000 である必要があります
    item_id: Annotated[int, Path(gt=0, le=1000)],
    # クエリパラメータにも数値検証を使用できます
    size: Annotated[float, Query(gt=0, lt=10.5)] = 5.0,
):
    return {"item_id": item_id, "size": size}

浮動小数点数検証

数値検証は浮動小数点数にも同様に適用されます。gt(より大きい)とge(以上)の違いは浮動小数点数のシナリオで重要です:

例

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(ge=1, le=1000)],
    # size は > 0 かつ < 10.5 である必要があります
    # 0.5 は有効な値ですが、0.0 と 0 は無効です(gt=0 は厳密に 0 より大きいため)
    size: Annotated[float, Query(gt=0, lt=10.5)],
):
    return {"item_id": item_id, "size": size}

パスパラメータとクエリパラメータの併用

同時に使用する場合PathとQuery、以下を使用するとAnnotatedパラメータの順序の問題を回避できます:

例

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    # Annotated を使用すると、パラメータの順序は重要ではありません
    item_id: Annotated[int, Path(title="商品ID", ge=1, le=1000)],
    q: Annotated[str | None, Query(max_length=50)] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

まとめ

パスパラメータ数値検証の核心ポイント:

  • を使用してAnnotated + Pathパスパラメータの検証ルールを宣言します
  • 数値検証:gt(より大きい)、ge(以上)、lt(より小さい)、le(以下)
  • PathとQuery同じ検証パラメータを共有します。文字列検証(min_lengthなど)とメタデータ(title、descriptionなど)
  • パスパラメータはデフォルト値を宣言するかどうかに関わらず常に必須です
その他の拡張