[FastAPI 공식문서] FastAPI - (7) 요청본문

이영락·2024년 10월 9일

개발자 기본기

목록 보기

41/53

요청 본문은 클라이언트가 API로 데이터를 보낼 때, 데이터를 담아 전송하는 방식입니다. FastAPI는 Pydantic 모델을 사용하여 요청 본문을 선언하고 처리할 수 있습니다.

🏖️ 요청 본문 처리하기

1. 요청 본문이란?

요청 본문은 클라이언트가 서버로 데이터를 전송할 때 사용되는 부분입니다. 요청 본문은 주로 POST, PUT, PATCH, DELETE 요청에서 사용됩니다. GET 요청에서 본문을 담는 것은 명세서에 정의되지 않았기 때문에 일반적으로 사용하지 않습니다.

2. Pydantic 모델을 사용하여 요청 본문 처리

FastAPI는 Pydantic의 BaseModel을 사용하여 요청 본문을 처리합니다. Pydantic은 데이터 검증과 타입 선언을 위한 강력한 도구이며, FastAPI와 통합되어 요청 본문을 쉽게 선언할 수 있습니다.

2.1 Pydantic 모델 정의

from fastapi import FastAPI
from pydantic import BaseModel

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

app = FastAPI()

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

Item 클래스는 Pydantic의 BaseModel을 상속받아 요청 본문으로 사용할 데이터를 정의합니다.
- name: 필수 str 타입.
- description: 선택적 str 타입 (기본값 None).
- price: 필수 float 타입.
- tax: 선택적 float 타입 (기본값 None).
create_item 함수는 요청 본문으로 전송된 item을 Item 모델로 처리하고, 데이터를 반환합니다.

2.2 요청 본문 JSON 예시

위에서 정의한 모델을 사용하면, 클라이언트가 다음과 같은 JSON 데이터를 전송할 수 있습니다.

{
    "name": "Foo",
    "description": "선택적인 설명란",
    "price": 45.2,
    "tax": 3.5
}

이 요청은 description과 tax 필드가 선택적이므로, 생략된 경우에도 유효한 요청으로 처리됩니다:

{
    "name": "Foo",
    "price": 45.2
}

3. 요청 본문과 경로 매개변수

경로 매개변수와 요청 본문을 동시에 선언할 수 있습니다. FastAPI는 경로 매개변수는 경로에서, 요청 본문은 JSON 데이터에서 자동으로 추출합니다.

3.1 경로 매개변수와 요청 본문 예시

from fastapi import FastAPI
from pydantic import BaseModel

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

app = FastAPI()

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.dict()}

경로 매개변수 item_id: URL에서 전달된 값.
요청 본문 item: Pydantic 모델 Item으로 JSON 데이터를 수신.
FastAPI는 자동으로 경로 매개변수와 요청 본문을 구분하여 처리합니다.

URL 예시:

http://127.0.0.1:8000/items/1 (경로 매개변수 item_id = 1)
본문 예시:

{
    "name": "Foo",
    "price": 45.2
}

응답 예시:

{
    "item_id": 1,
    "name": "Foo",
    "price": 45.2
}

4. 요청 본문 + 경로 매개변수 + 쿼리 매개변수

요청 본문, 경로 매개변수, 쿼리 매개변수를 동시에 사용할 수도 있습니다. FastAPI는 각 매개변수를 적절히 인식하여 처리합니다.

4.1 요청 본문 + 경로 + 쿼리 매개변수 예시

from fastapi import FastAPI
from pydantic import BaseModel

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

app = FastAPI()

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: str | None = None):
    result = {"item_id": item_id, **item.dict()}
    if q:
        result.update({"q": q})
    return result

item_id: 경로 매개변수.
item: 요청 본문으로부터 전달된 Pydantic 모델 데이터.
q: 선택적 쿼리 매개변수.

URL 예시:

http://127.0.0.1:8000/items/1?q=extra

본문 예시:

{
    "name": "Foo",
    "price": 45.2
}

응답 예시:

{
    "item_id": 1,
    "name": "Foo",
    "price": 45.2,
    "q": "extra"
}

5. Pydantic의 강력한 검증 기능

Pydantic을 사용하여 요청 본문을 선언하면, FastAPI는 다음을 자동으로 처리합니다:

데이터 검증: 요청 본문이 Pydantic 모델에 맞는지 확인합니다.
타입 변환: 요청 본문을 Python 타입으로 변환합니다.
자동 에러 반환: 데이터가 잘못되었을 때, 명확한 오류 메시지를 반환합니다.

5.1 잘못된 요청 본문 예시

만약 클라이언트가 잘못된 데이터를 전송하면, FastAPI는 친절한 오류 메시지를 반환합니다.

요청 본문:

{
    "name": "Foo",
    "price": "forty-five"
}

응답:

{
  "detail": [
    {
      "loc": ["body", "price"],
      "msg": "value is not a valid float",
      "type": "type_error.float"
    }
  ]
}

6. 편집기 지원 및 자동 문서화

FastAPI와 Pydantic을 사용하면, 편집기 자동완성과 타입 힌팅을 지원받을 수 있습니다. 또한 FastAPI는 요청 본문과 관련된 자동 문서화를 제공합니다.

6.1 자동 문서화

FastAPI는 OpenAPI 스키마를 자동으로 생성하여, 요청 본문에 대한 명확한 설명을 제공합니다.
Swagger UI에서 http://127.0.0.1:8000/docs로 접속하면, 요청 본문에 대한 정보가 자동으로 표시됩니다.
ReDoc에서도 http://127.0.0.1:8000/redoc를 통해 대체 문서를 볼 수 있습니다.

7. 요약

요청 본문은 클라이언트가 서버로 데이터를 전송하는 방식이며, 주로 POST, PUT, PATCH 요청에 사용됩니다.
Pydantic 모델을 사용하여 요청 본문을 선언하면, FastAPI는 데이터 검증, 타입 변환, 오류 처리 등을 자동으로 처리합니다.
경로 매개변수, 쿼리 매개변수와 함께 요청 본문을 사용할 수 있으며, FastAPI는 이를 자동으로 구분하고 처리합니다.
자동 문서화와 편집기 지원을 통해 개발 생산성을 높일 수 있습니다.