FastAPI 04. 바디의 예시 만들기

OpenAPI를 지원하는 FastAPI를 더 잘 활용하는 방법은 스키마 활용이라고 생각한다. API를 작성하고, 간단하게 설명해 줄 수 있지만, API를 제대로 작성하고 또 제개도 활용학 위해서는 OpenAPI를 따라 스키마를 작성하는 것이 필요하다고 생각한다. 그렇게 한다면 입출력 예시뿐만 아니라 가능한 상태 코드 등을 쉽게 이해할 수 있다. 이는 API 개발뿐만 아니라 테스트나 유지 보수에도 도움 되는 작업이라고 생각한다.
FastAPI에서는 이를 달성하기 위해 Pydantic을 사용하는 방법과 FatsAPI에서 제공하는 Body()함수를 사용하는 방법을 제공한다.

Pydantic을 사용하는 방법

class Item(BaseModel):
    id: int
    name: str
    description: str | None = Field(default=None, max_length=300)
    price: int
    image: list[Image] | None = None

    class Config:
        schema_extra = {
            "example": {
                "name": "foo",
                "description": "baa",
                "price": 50,
            }
        }

Pydantic을 활용하는 첫 번째 방법은 모델 내부에 Config클래스를 생성, schema_extra변수를 선언, 예시를 딕셔너리로 작성하면 된다. 예시는 실제 검증에 사용되지 않지만, API 사용자는 이러한 예시로부터 API 활용에 대한 방법을 배울 수 있기 때문에 자세하게 작성하는 것이 좋다.

class Image(BaseModel):
    url: HttpUrl
    name: str = Field(example="some name")

또 다른 방법은 Field 함수를 사용하는 방법인데, 데이터 검증에도 사용할 수 있지만, 예시를 같이 작성할 수 있다.

Body()를 사용하는 방법

@app.post("/offers/")
async def offer(
    offer: Offer = Body(
        example={
            "name": "foo",
            "price": 50.5,
            "items": [
                {
                    "name": "foo1",
                    "description": "baa1",
                    "price": 30,
                },
                {
                    "name": "foo2",
                    "description": "baa2",
                    "price": 60,
                },
            ],
        }
    )
):
    return offer

FastAPI에서 제공하는 방법으로는 Body()함수를 사용하는 것이다. 예시를 생성하는 것은 바디뿐만 아니라 다른 매개 변수 등을 지정하는 함수, Path, Query, Header, Cookie, Form, File 함수에도 활용가능하다. FastAPI 공식문서를 살펴보면. OpenAPI 스키마를 더 자세하게 작성하는 방법을 공유하고 있다. 다른 프로젝트를 진행하면서 스키마를 상세하게 구현했던 적은 있지만, 이런 간단한 글에서는 넘어가는 것이 좋을 것 같다. 다음에 상세하게 다루는 일이 있으면 공유하도록 하겠다.