쿼리 매개변수 (Query Parameters)

?key=value 기본값 Optional list Query

경로에 없는 함수 인자는 자동으로 쿼리스트링에서 읽습니다.

1. 기본값 = 선택 매개변수

@app.get("/items")
def list_items(skip: int = 0, limit: int = 10):
    return items[skip : skip + limit]

# "/items"                -> skip=0,  limit=10
# "/items?skip=20&limit=5" -> skip=20, limit=5

2. 필수 쿼리 · 선택 쿼리

# 기본값이 없으면 필수
@app.get("/search")
def search(q: str):                 # ?q= 없으면 422
    ...

# None 허용 = 선택
@app.get("/search2")
def search2(q: str | None = None):
    ...

3. bool 변환

@app.get("/items/{id}")
def read(id: int, verbose: bool = False):
    ...

# ?verbose=1 / true / True / yes / on  -> True
# ?verbose=0 / false / no / off        -> False

4. 리스트로 여러 값 받기

from typing import Annotated
from fastapi import Query

@app.get("/items")
def read(tags: Annotated[list[str], Query()] = []):
    return {"tags": tags}

# "/items?tags=a&tags=b"  ->  tags == ["a", "b"]

5. 검증·메타데이터

@app.get("/items")
def read(
    q: Annotated[str | None, Query(
        min_length=2, max_length=50,
        pattern=r"^[a-z]+$",
        description="검색어",
        deprecated=False,
    )] = None,
):
    ...

"API 스키마는 코드가 곧 문서다 (/docs)"