fastapi/docs/ko/docs/tutorial/query-param-models.md

쿼리 매개변수 모델

연관된 쿼리 매개변수 그룹이 있다면 이를 선언하기 위해 Pydantic 모델을 생성할 수 있습니다.

이렇게 하면 여러 곳에서 모델을 재사용할 수 있을 뿐만 아니라, 매개변수에 대한 검증 및 메타데이터도 한 번에 선언할 수 있습니다. 😎

/// note | 참고

이 기능은 FastAPI 버전 0.115.0부터 지원됩니다. 🤓

///

Pydantic 모델과 쿼리 매개변수

필요한 쿼리 매개변수를 Pydantic 모델 안에 선언한 다음, 매개변수를 Query로 선언합니다:

{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}

FastAPI는 요청의 쿼리 매개변수에서 각 필드의 데이터를 추출해 정의한 Pydantic 모델을 제공합니다.

문서 확인하기

/docs의 문서 UI에서 쿼리 매개변수를 확인할 수 있습니다:

추가 쿼리 매개변수 금지

몇몇의 특이한 경우에 (흔치 않지만), 받으려는 쿼리 매개변수를 제한하고 싶을 수 있습니다.

Pydantic의 모델 설정을 사용해 어떤 extra 필드도 forbid할 수 있습니다:

{* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *}

클라이언트가 쿼리 매개변수로 추가적인 데이터를 보내려고 하면 에러 응답을 받게 됩니다.

예를 들어, 아래와 같이 클라이언트가 tool 쿼리 매개변수에 plumbus 값을 보내려고 하면:

https://example.com/items/?limit=10&tool=plumbus

쿼리 매개변수 tool이 허용되지 않는다는 에러 응답을 받게 됩니다:

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["query", "tool"],
            "msg": "Extra inputs are not permitted",
            "input": "plumbus"
        }
    ]
}

요약

FastAPI에서 쿼리 매개변수를 선언할 때 Pydantic 모델을 사용할 수 있습니다. 😎

/// tip | 팁

스포일러 경고: Pydantic 모델을 쿠키와 헤더에도 사용할 수 있지만, 이에 대해서는 이후 튜토리얼에서 읽게 될 것입니다. 🤫

///