Body - 필드
Body - 필드 (Body - Fields)
경로 연산 함수 파라미터에서 Query, Path, Body로 추가 검증과 메타데이터를 선언할 수 있듯이, Pydantic 모델 안에서는 Pydantic의 Field를 써서 검증과 메타데이터를 선언할 수 있어요.
출처: 공식문서
Field 임포트하기
먼저 임포트해야 해요:
from typing import Annotated
from fastapi import Body, FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = Field(
default=None, title="The description of the item", max_length=300
)
price: float = Field(gt=0, description="The price must be greater than zero")
tax: float | None = None
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Annotated[Item, Body(embed=True)]):
results = {"item_id": item_id, "item": item}
return results
경고 —
Field는pydantic에서 직접 임포트한다는 점을 주목하세요. 나머지(Query,Path,Body등)처럼fastapi에서 임포트하는 게 아니에요.
팁 — 가능하면
Annotated버전을 쓰는 게 좋아요. (non-Annotated 버전도 있어요.item: Item = Body(embed=True)처럼 쓰면 돼요.)
모델 속성 선언하기
그다음 모델 속성과 함께 Field를 쓸 수 있어요:
from typing import Annotated
from fastapi import Body, FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = Field(
default=None, title="The description of the item", max_length=300
)
price: float = Field(gt=0, description="The price must be greater than zero")
tax: float | None = None
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Annotated[Item, Body(embed=True)]):
results = {"item_id": item_id, "item": item}
return results
Field는 Query, Path, Body와 같은 방식으로 동작해요. 같은 파라미터들을 모두 갖고 있어요, 등.
기술적 세부사항 — 사실 Query, Path와 앞으로 볼 다른 것들은 공통 Param 클래스(이 클래스는 Pydantic의 FieldInfo 클래스의 서브클래스)의 서브클래스 객체들을 만들어요. 그리고 Pydantic의 Field도 FieldInfo 인스턴스를 반환해요. Body도 FieldInfo의 서브클래스 객체를 직접 반환해요. 그리고 앞으로 볼 다른 것들 중 Body 클래스의 서브클래스인 것들도 있어요. fastapi에서 Query, Path 등을 임포트할 때 실제로는 특수 클래스를 반환하는 함수들이라는 걸 기억하세요.
팁 — 타입, 기본값,
Field가 있는 각 모델 속성이 경로 연산 함수의 파라미터와,Path,Query,Body대신Field를 쓴다는 점만 빼고 같은 구조를 갖는 걸 주목하세요.
추가 정보 넣기
Field, Query, Body 등에서 추가 정보를 선언할 수 있어요. 그리고 그것이 생성된 JSON Schema에 포함돼요.
추가 정보 넣기에 대해 더 자세히는 나중에 문서에서, 예시(example)를 선언하는 법을 배울 때 알게 돼요.
경고 —
Field에 전달된 추가 키(extra keys)는 여러분 애플리케이션의 결과 OpenAPI 스키마에도 존재하게 돼요. 이 키들이 반드시 OpenAPI 명세의 일부는 아닐 수 있으므로, OpenAPI validator 같은 일부 OpenAPI 도구는 여러분이 생성한 스키마에서 동작하지 않을 수도 있어요.
요약 (Recap)
Pydantic의 Field를 써서 모델 속성에 추가 검증과 메타데이터를 선언할 수 있어요.
추가 키워드 인자를 써서 추가 JSON Schema 메타데이터를 전달할 수도 있어요.