요청 본문

클라이언트(브라우저라고 합시다)에서 API로 데이터를 보내야 할 때, 요청 본문을 보냅니다.

요청 본문은 클라이언트에서 API로 보내는 데이터입니다. 응답 본문은 API에서 클라이언트로 보내는 데이터입니다.

API는 대부분 응답 본문을 보냅니다. 하지만 클라이언트는 항상 요청 본문을 보낼 필요는 없습니다.

요청 본문을 선언하려면, 강력한 힘과 장점을 가진 Pydantic 모델을 사용하면 됩니다.

정보

데이터를 보내기 위해서 다음 중 하나를 사용하면 됩니다: POST (좀 더 일반적), PUT, DELETE 또는 PATCH.

GET 요청으로 본문을 보내는 것은 사양에 정의되지 않은 동작이 있지만, 그럼에도 FastAPI는 매우 복잡/극단적 사용 사례에 대해서만 지원됩니다.

이것은 권장되지 않기 때문에 Swagger UI 대화형 문서는 GET을 사용할 경우 본문에 대한 문서를 보여주지 않고, 중간에 있는 프록시가 지원하지 않을수 있습니다.

Pydantic의 BaseModel 임포트

우선, pydantic에서 BaseModel를 임포트해야 합니다:

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


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

데이터 모델 생성

이제 BaseModel을 상속하는 클래스로 데이터 모델을 선언합니다.

모든 어트리뷰트에 표준 파이썬 타입을 사용합니다:

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


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

쿼리 매개변수를 선언할 때와 마찬가지로, 모델 어트리뷰트에 기본값이 있으면 필수가 아닙니다. 그렇지 않으면 필수입니다. 선택적으로 만들려면 None을 사용합니다.

예를 들어, 위에서 이 모델은 JSON "object"(또는 파이썬 dict)를 다음과 같이 선언합니다:

{
    "name": "Foo",
    "description": "An optional description",
    "price": 45.2,
    "tax": 3.5
}

...description과 tax는 (None 값을 기본값으로 하면서) 선택적이며, 이 JSON "object" 또한 유효합니다:

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

매개변수로 선언

이를 경로 동작에 추가하려면 경로 및 쿼리 매개변수를 선언한 것과 동일한 방식으로 선언합니다:

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


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

...그리고 생성한 Item 모델로 타입을 선언합니다.

결과

파이선 타입 선언만으로 FastAPI는:

• 요청 본문을 JSON으로 읽습니다.
• (필요하다면) 해당 타입을 변환합니다.
• 데이터를 검증합니다.
  • 데이터가 유효하지 않다면, 잘못된 데이터가 어디에서 무엇인지 정확하게 표시하는 멋지고 명확한 오류를 반환합니다.
• 매개변수 item에 수신한 데이터를 전달합니다.
  • 함수에 Item 타입으로 선언함으로써, 모든 어트리뷰트와 그 타입에 대한 편집기 지원(자동완성 등) 역시 제공합니다.
• 모델의 JSON 스키마 정의를 생성하고, 프로젝트에 적합한 경우 원하는 곳 어디에서나 사용할 수도 있습니다.
• 이 스키마들은 생성한 OpenAPI 스키마의 일부가 되며 자동 UI 문서화에 사용됩니다.

자동 문서

모델의 JSON 스키마는 OpenAPI 생성 스키마의 일부가 되며 대화형 API 문서에 표시됩니다:

그리고 이를 필요로 하는 각 경로 동작 내의 API 문서에서도 사용됩니다:

편집기 지원

편집기에서 함수 내부 모든 곳(Pydantic 모델 대신 dict를 받은 경우에는 발생하지 않습니다)에서 타입 힌트와 자동완성을 얻을 수 있습니다:

잘못된 타입 작업에 대한 오류 검사도 받습니다:

이는 우연이 아니며, 전체 프레임워크는 이러한 설계를 중심으로 구축되었습니다.

그리고 구현하기 전에 설계 단계에서 철저히 테스트하여 모든 편집자와 함께 작동하는지 확인했습니다.

이를 지원하기 위해 Pydantic 자체에도 약간의 변경이 있었습니다.

이전 스크린샷은 비주얼 스튜디오 코드에서 찍은 것입니다.

하지만 PyCharm 및 대부분의 다른 파이썬 편집기에서 동일한 편집기 지원을 얻을 수 있습니다:

팁

PyCharm을 편집기로 사용하고 있다면, Pydantic PyCharm 플러그인을 사용할 수 있습니다.

다음을 통해 Pydantic 모델에 대한 편집기 지원을 개선합니다:

• 자동완성
• 타입 검사
• 리팩토링
• 검색
• 검사(Inspection)

모델 사용

함수 내부에서 모델 객체의 모든 어트리뷰트에 직접 접근할 수 있습니다:

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

요청 본문 + 경로 매개변수

경로 매개변수와 요청 본문을 동시에 선언할 수 있습니다.

FastAPI는 경로 매개변수와 일치하는 함수 매개변수는 경로에서 가져와야 함을, Pydantic 모델로 선언한 함수 매개변수는 요청 본문에서 가져와야 함을 인지합니다.

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


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

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

본문, 경로 그리고 쿼리 매개변수 전부를 동시에 선언할 수도 있습니다.

FastAPI는 각각을 인식하고 올바른 위치에서 데이터를 가져옵니다.

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


app = FastAPI()


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

함수 매개변수는 다음으로 인식됩니다:

• 매개변수가 경로에도 선언되었다면 경로 매개변수로 사용됩니다.
• 매개변수가 단수형(int, float, str, bool 등)이면 쿼리 매개변수로 해석됩니다.
• 매개변수가 Pydantic 모델 타입으로 선언되었다면 요청 본문으로 해석됩니다.

참고

FastAPI는 q가 = None이므로 선택적이라는 것을 인지합니다.

Optional[str]에 있는 Optional은 FastAPI(FastAPI는 str 부분만 사용합니다)가 사용하는게 아니지만, Optional[str]은 편집기에게 코드에서 오류를 찾아낼 수 있게 도와줍니다.

Pydantic 없이 사용하기

Pydantic 모델을 사용하고 싶지 않다면, 본문(Body) 매개변수를 사용할 수 있습니다. 본문 - 다중 매개변수: 본문의 단수형 값 문서를 보세요.