본문 - 필드

Path와 Query에서처럼 Body에서도 Pydantic의 Field를 사용하여 모델 내의 검증 규칙을 선언하고, 추가적인 메타 정보를 제공할 수 있습니다. 이를 통해 API의 요청 본문(body)에 대한 유효성 검사를 보다 명확하게 정의할 수 있습니다.

Field import

먼저 pydantic에서 Field를 import 해야합니다.

Python 3.8+

from typing import Annotated

from nexify import Body, Nexify
from pydantic import BaseModel, Field

app = Nexify()


class Item(BaseModel):
    name: str
    description: Annotated[
        str | None,
        Field(
            default=None,
            description="The description of the item",
            max_length=300,
        ),
    ]
    price: Annotated[
        float,
        Field(
            gt=0,
            description="The price must be greater than zero",
        ),
    ]
    tax: Annotated[
        float | None,
        Field(
            default=None,
            gt=0,
        ),
    ]


@app.post("/items")
def create_item(item: Annotated[Item, Body()]):
    return item.model_dump()

모델 속성 선언

Field를 사용하여 Pydantic 모델의 각 속성을 선언할 수 있습니다.

Python 3.8+

from typing import Annotated

from nexify import Body, Nexify
from pydantic import BaseModel, Field

app = Nexify()


class Item(BaseModel):
    name: str
    description: Annotated[
        str | None,
        Field(
            default=None,
            description="The description of the item",
            max_length=300,
        ),
    ]
    price: Annotated[
        float,
        Field(
            gt=0,
            description="The price must be greater than zero",
        ),
    ]
    tax: Annotated[
        float | None,
        Field(
            default=None,
            gt=0,
        ),
    ]


@app.post("/items")
def create_item(item: Annotated[Item, Body()]):
    return item.model_dump()

Path 및 Query에서 사용한 것과 동일한 속성들을 사용할 수 있으며, 다음과 같은 속성이 포함됩니다:

• gt, ge, lt, le: 숫자 값의 크기 제한 (gt=0은 0보다 커야 함, ge=0은 0 이상)
• min_length, max_length: 문자열 길이 제한 (min_length=2, max_length=50)
• regex: 정규 표현식을 이용한 문자열 검증 (regex="^[a-zA-Z0-9_-]+$")

이것들 이외에도 다양한 것들을 사용할 수 있습니다. 자세한 내용은 Pydantic 공식문서를 참고하세요.

Body()를 사용한 추가 정보

Body() 내부에 openapi_examples를 활용하여 API 문서에서 표시될 예제 값을 설정할 수 있습니다.

Python 3.8+

from typing import Annotated

from nexify import Body, Nexify
from pydantic import BaseModel

app = Nexify()


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


@app.post("/items")
def create_item(
    item: Annotated[
        Item,
        Body(
            openapi_examples={
                "simple_example": {
                    "summary": "Simple Example",
                    "description": "A simple example of a request to create an item",
                    "value": {
                        "name": "Item Name",
                        "description": "Item Description",
                        "price": 10.5,
                        "tax": 1.5,
                    },
                }
            },
        ),
    ],
):
    return item.model_dump()

API 문서에서 아래와 같이 에제 값을 확인할 수 있습니다.

Info

Field(..., example=1234)와 같은 방식으로 기본 예제 값을 설정할 수도 있지만, OpenAPI 문서에 더 자세한 예제를 추가하려면 Body()의 openapi_examples를 활용하는 것이 좋습니다.