[FastAPI] [Chapter 9] 스키마 - 응답

스키마에서는 API의 요청과 응답을 정확한 타입으로 정의한다. 

이번 장에서는 먼저 응답에 대해 알아본다.

 

01 응답 타입 정의

 

api/schemas/task.py 

from pydantic import BaseModel, Field 

class Task(BaseModel):
    id: int 
    title: str | None = Field(None, example="세탁소에 맡긴 것을 찾으러 가기")
    done: bool = Field(False, description="완료 플래그")

 

이 파일은 FastAPI의 스키마를 나타낸다. 

API의 스키마는 API 요청과 응답의 타입을 정의하기 위한 것

 

이 스키마를 이용하여 실제로 API 응답을 반환할 수 있는지 확인해 본다. 

api/routers/task.py의 list_tasks()함수를 아래와 같이 고쳐본다.

 

api/routers/task.py

from fastapi import APIRouter 

import api.schemas.task as task_schema


router = APIRouter()

@router.get("/tasks", response_model=list[task_schema.Task])
async def list_tasks():
    return [task_schema.Task(id=1, title="첫번째 ToDo 작업")]

@router.post("/tasks")
async def create_task():
    pass

@router.put("/tasks/{task_id}")
async def update_task():
    pass

@router.delete("/tasks/{task_id}")
async def delete_task():
    pass

 

 

이제 Swagger UI에 접속하면 API에 응답 (Response body)이 추가된 것을 확인할 수 있다.

 

 

02 응답 타입 정의에 대한 설명 

앞서 api/schemas/task.py에서 class Task를 정의하였다. 

from pydantic import BaseModel, Field 

class Task(BaseModel):
    id: int 
    title: str | None = Field(None, example="세탁소에 맡긴 것을 찾으러 가기")
    done: bool = Field(False, description="완료 플래그")

 

FastAPI의 스키마 모델임을 나타내는 BaseModel 클래스를 상속받아 Task 클래스를 만들고 있다.

 

Task 클래스는 id, title, done의 3가지 필드를 가진다.

각 필드에는 int, str | None, bool의 타입 힌트가 추가되어 있다. 

또한 오른쪽의 Field는 필드에 대한 부가적인 정보를 기술한다.

 

첫번째 변수 id는 필드의 기본값을 나타낸다.

title은 None,

done은 False를 기본값으로 설정하고 있다. 

 

title을 보면 example이 있다. 

example은 필드의 값을 예를 들어 설명한다. 

 

done은 완료 플래그를 나타낸다.

description은 인수에 대해 설명한다.

 

 

이러한 스키마 정의는 Swagger UI 하단에서도 확인할 수 있다.

 

 

 

라우터에서 앞서 정의한 스키마를 이용해 API의 요청과 응답을 정의하였다.

GET /tasks에서는 요청 파라미터나 요청 본문을 받지 않으므로 응답만 정의한다.

 

응답의 스키마로 경로 동작 함수의 데코레이터에 response_model을 설정한다.

GET /tasks는 스키마에 정의한 Task 클래스를 여러개 반환하므로 리스트로 정의한다.

response_model=list[task_schema.Task]가 된다.

 

현 시점에서는 아직 DB와의 연결은 없으며, Task 데이터 저장은 고려되지 않은 상태이다.

일단 더미 데이터를 항상 반환하는 함수로 정의해 둔다. 

 

id와 title을 임의의 내용으로 지정하고, done은 기본적으로 False이므로 여기서는 지정하지 않는다. 

더미 데이터로 [task_schema.Task(id=1, title="첫번째 ToDo 작업")]을 반환한다. 

 

 

 

파이썬을 포함한 동적 타입 지정 언어에서는 일반적으로 타입을 의식하지 않기 때문에 타입 힌트가 없으면 API가 예상치 못한 타입으로 값을 반환하게 된다. 결과적으로 프론트엔드에서 오류가 발생하여 애플리케이션의 사용자에게 영향을 미칠  수 있다. 타입 불일치를 발지하기 위해서는 유효성 검사가 필요하다.

일반적으로 title의 내용이 str이라는 유효성 검사를 자체적으로 준비하게 된다. 

타입 힌트를 이용해 자동으로 유효성 검사를 해주기 때문에 FastAPI는 '타입 안전'하다.