FastAPI クエリパラメータバリデーション

FastAPI では、クエリパラメータに追加のバリデーションルールとメタデータを宣言できます（文字列長の制限や正規表現のマッチなど）。QueryとAnnotatedこれにより、関数ロジックを変更することなくパラメータバリデーションを強化できます。

基本バリデーション

以下の例では、クエリパラメータにq最大長制限を追加します：

例

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
# 使用 Annotated + Query 添加校验
q: Annotated[str | None, Query(max_length=50)] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results

コードの説明：

部分	説明
`Annotated[str \| None, ...]`	型アノテーション、`q`文字列または None を指定できます。
`Query(max_length=50)`	バリデーションルール、`q`最大長は50文字です。
`= None`	デフォルト値、これによりパラメータはオプションになります。

FastAPI では、Annotated方式でバリデーションを宣言することを推奨しており、Queryをデフォルト値として使用するのではありません。Annotated方式では、関数のデフォルト値が真のデフォルト値となり、Python の直感に合致し、エディタや型チェックツールのサポートも向上します。

さらにバリデーションを追加

複数のバリデーションルールを同時に追加できます：

例

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
# 最小長さ、最大長さ、正規表現を同時に制限する
q: Annotated[str | None, Query(min_length=3, max_length=50, pattern="^fixedquery$")] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results

文字列バリデーションパラメータ：

パラメータ	型	説明
`min_length`	`int`	最小長
`max_length`	`int`	最大長
`pattern`	`str`	正規表現マッチ

正規表現^fixedquery$の意味：

^-- 次の文字で始まる必要があります
fixedquery-- 値は正確に等しい必要がありますfixedquery
$-- ここで終了し、後ろに他の文字があってはなりません

デフォルト値付きバリデーション

クエリパラメータにデフォルト値とバリデーションルールを同時に設定できます：

例

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
# デフォルト値は "fixedquery" で、かつ最小長は 3 である必要があります
q: Annotated[str, Query(min_length=3)] = "fixedquery",
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results

あらゆる型のデフォルト値（非NoneNone 値）は、パラメータをオプションにします。デフォルト値がなく、Query(default=...)None もないパラメータは必須です。

必須パラメータ

を使用するQueryとき、デフォルト値を宣言しないと、パラメータは必須になります：

例

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
# = None がないため、q は必須パラメータです
q: Annotated[str, Query(min_length=3)],
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
results.update({"q": q})
return results

必須だが None を許容

クライアントが値を送信しなければならない場合がありますが、値は None にできます。None：

例

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
# クライアントは q パラメータを提供する必要がありますが、値は None でも構いません
q: Annotated[str | None, Query(min_length=3)],
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results

クエリパラメータのリスト / 複数の値

を使用すると、Query複数の値を受け取るクエリパラメータを宣言できます：

例

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
q は URL に複数回出現でき、値はリストとして収集されます
q: Annotated[list[str] | None, Query()] = None,
):
query_items = {"q": q}
return query_items

アクセスするhttp://127.0.0.1:8000/items/?q=foo&q=barと、次が返されます：

{"q": ["foo", "bar"]}

型がlistのクエリパラメータを宣言するには、Query()を明示的に使用する必要があります。そうしないと、FastAPI はそれをリクエストボディとして解釈します。

メタデータの宣言

Queryまた、パラメータにメタデータを追加できます。これらの情報は API ドキュメントに表示されます：

例

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
q: Annotated[str | None, Query(
title="查询字符串", # 参数标题
description=商品を絞り込むためのクエリ文字列, # 参数描述
min_length=3,
max_length=50,
alias="item-query", # URL内のパラメータ名の別名
deprecated=True, # 非推奨としてマーク
)] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results

メタデータパラメータの説明：

パラメータ	説明	使用シナリオ
`alias`	URL でのパラメータ名のエイリアス	パラメータ名にハイフンが含まれる場合（例：`item-query`）、有効な Python 変数名ではないとき
`title`	パラメータのタイトル	ドキュメントにパラメータのタイトルを表示します
`description`	パラメータの説明	ドキュメントにパラメータの詳細な説明を表示します
`deprecated`	非推奨としてマーク	パラメータは引き続き使用できますが、ドキュメントでは「非推奨」とマークされます。
`include_in_schema`	API ドキュメントに表示するかどうか	に設定すると、`False`パラメータを非表示にできます。

OpenAPI からパラメータを除外する

クエリパラメータを API ドキュメントに表示したくない場合：

例

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
# hidden_query は API ドキュメントに表示されませんが、それでも使用できます。
hidden_query: Annotated[str | None, Query(include_in_schema=False)] = None,
):
if hidden_query:
return {"hidden_query": hidden_query}
return {"items": [{"item_id": "Foo"}]}

まとめ

クエリパラメータバリデーションの核心ポイント：

を使用してAnnotated + Queryバリデーションルールを宣言します（推奨方法）
文字列バリデーション：min_length、max_length、pattern
デフォルト値なし = 必須パラメータ、デフォルト値あり = オプションパラメータ
aliasURL 内で Python 変数名として有効でないパラメータ名に使用します
deprecated=True非推奨のパラメータをマーク
を使用してlist[str]同じ名前の複数のクエリパラメータを受け取ります

その他の拡張

実践プロジェクト