[fastapi] Field를 사용하여 Request Body로 데이터 받기

아래 코드는 Python 3.10+ 에서 동작한다.

1. Field란 무엇인가?

Field는 FastAPI에서 Request Body로 전달되는 데이터의 필드를 정의할 때 사용하는 도구이다. Field를 사용하면 기본값 설정, 유효성 검사, 메타데이터 추가 등을 할 수 있다. 이 기능은 주로 Pydantic의 BaseModel과 함께 사용된다.

2. 기본적인 Field 사용법

우선, Pydantic의 BaseModel을 사용하여 Request Body를 정의하는 기본적인 방법을 알아보자.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

@app.post("/items/")
async def create_item(item: Item):
    return item

위 코드에서는 Item이라는 Pydantic 모델을 정의하여 Request Body로 데이터를 받는다. 그러나, 이 상태에서는 필드의 기본값이나 유효성 검사에 대한 설정이 제한적이다. 이때 Field를 사용하면 더 세밀하게 제어할 수 있다.

3. Field를 사용하여 Request Body 필드 제어하기

Field를 사용하여 각 필드에 대한 제약 조건이나 설명을 추가할 수 있다.

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

class Item(BaseModel):
    name: str = Field(..., title="The name of the item", max_length=100)
    description: str | None = Field(None, title="The description of the item", max_length=300)
    price: float = Field(..., gt=0, description="The price of the item, must be greater than zero")
    tax: float | None = Field(None, ge=0, description="The tax rate of the item, must be zero or more")

@app.post("/items/")
async def create_item(item: Item):
    return item

위 코드에서 Field를 사용하여 각 필드의 동작을 제어하는 방법을 알아보자.

name: 필수 필드(...), 최대 길이 100자의 제한과 함께 제목(title)을 지정한다.
description: 선택 필드이며(None), 최대 길이 300자로 제한된다.
price: 필수 필드(...), 0보다 큰 값만 허용합니다(gt=0). 이 필드는 아이템의 가격을 의미하며, 설명(description)이 추가되었다.
tax: 선택 필드(None), 0 이상의 값만 허용된다(ge=0).

이와 같이 Field를 사용하면 각 필드에 대해 더 세밀한 제어가 가능하며, API 문서에도 해당 제약 조건이 반영된다.

4. Field의 추가적인 사용 예시

Field는 기본값 설정이나 유효성 검사를 넘어서, 메타데이터 추가 및 정규 표현식 사용 등 다양한 기능을 제공한다.

예시 1: 기본값 설정

class Item(BaseModel):
    name: str = Field("Default Name", title="The name of the item")
    description: str | None = Field("No description", title="The description of the item")
    price: float = Field(10.0, gt=0, description="The price of the item, default is 10.0")

위 예시에서는 각 필드에 기본값을 설정했다. 클라이언트가 값을 제공하지 않으면 기본값이 사용된다.

예시 2: 정규 표현식을 사용한 유효성 검사

class User(BaseModel):
    username: str = Field(..., regex="^[a-zA-Z0-9_]+$", max_length=20, title="Username for login")
    email: str = Field(..., regex="^[\w\.-]+@[\w\.-]+\.\w+$", title="The email of the user")

username: 영문자, 숫자, 밑줄만 허용하며, 최대 길이는 20자이다.
email: 이메일 형식을 정규 표현식으로 검증한다.

이와 같이 Field를 사용하여 정교한 유효성 검사를 구현할 수 있다.

5. Field를 사용한 Request Body의 JSON Schema

FastAPI는 Field로 정의한 모든 메타데이터와 제약 조건을 OpenAPI 스펙에 맞게 자동으로 문서화합니다. 이를 통해 API 문서에서 필드의 유효성 검사 및 설명을 쉽게 확인할 수 있습니다.

{
  "title": "Item",
  "type": "object",
  "properties": {
    "name": {
      "title": "The name of the item",
      "type": "string",
      "maxLength": 100
    },
    "description": {
      "title": "The description of the item",
      "type": "string",
      "maxLength": 300
    },
    "price": {
      "title": "The price of the item",
      "type": "number",
      "description": "The price of the item, must be greater than zero",
      "exclusiveMinimum": 0
    },
    "tax": {
      "title": "The tax rate of the item",
      "type": "number",
      "description": "The tax rate of the item, must be zero or more",
      "minimum": 0
    }
  },
  "required": ["name", "price"]
}

위와 같은 JSON Schema가 자동으로 생성되어 API 문서화 도구에서 확인할 수 있습니다.