FastAPI는 현대적인 웹 API를 구축하기 위한 고성능 Python 프레임워크로, Starlette과 Pydantic을 기반으로 하고 있습니다. FastAPI는 개발자가 빠르게 API를 구축할 수 있도록 도와주지만, 이 프레임워크의 진정한 힘은 스키마와 타입 정의에 있습니다. 이 글에서는 FastAPI의 스키마를 이해하고, 응답 및 타입 정의가 어떻게 API의 안정성, 문서화, 유용성을 높이는지를 살펴보겠습니다.
1. FastAPI란?
FastAPI는 빠르고 쉽게 API를 구축할 수 있도록 도와주는 Python 웹 프레임워크입니다. 비동기 프로그래밍 지원, 데이터 검증 및 자동 문서화의 강력한 기능을 제공합니다. FastAPI는 특히 RESTful API를 설계하는 데 매우 유용하며, Pydantic을 통해 데이터 검증, 직렬화 및 문서화를 지원합니다.
2. 스키마의 개념
스키마(Schema)는 데이터 구조를 정의하는 청사진입니다. API에서 스키마를 정의함으로써 요청과 응답에서 어떤 데이터가 사용되는지 명확하게 알 수 있습니다. FastAPI에서는 Pydantic 모델을 사용하여 쉽게 스키마를 정의할 수 있습니다. 이러한 모델은 데이터의 유효성 검사를 자동으로 수행하고, 비즈니스 로직을 단순화합니다.
2.1 Pydantic 소개
Pydantic은 Python 데이터 클래스를 기반으로 하는 데이터 검증 및 설정 관리 라이브러리입니다. FastAPI와 통합되어 유효성 검사, 데이터 변환 및 스키마 생성 기능을 제공합니다. Pydantic은 타입 힌트를 사용하여 데이터를 정의하고, 덕타이핑(duck typing)을 통해 데이터 타입의 유효성을 검사합니다.
3. 타입 정의의 힘
FastAPI에서 타입 시스템은 API의 신뢰성을 높이고, 자동 문서화를 가능하게 합니다. 타입을 명시하면, FastAPI는 이를 기반으로 자동으로 API 문서를 생성합니다. 예를 들어, 사용자가 잘못된 타입의 데이터를 요청하면 FastAPI는 자동으로 오류를 반환합니다. 이를 통해 개발자는 보다 안전하고 일관된 API를 유지할 수 있습니다.
3.1 예제 코드와 설명
아래는 간단한 FastAPI 앱을 만드는 예제입니다.
from fastapi import FastAPI
from pydantic import BaseModel
from typing import List
app = FastAPI()
class Item(BaseModel):
id: int
name: str
price: float
class ResponseModel(BaseModel):
message: str
items: List[Item]
@app.get("/items/", response_model=ResponseModel)
async def get_items():
fake_items = [
{"id": 1, "name": "Item 1", "price": 10.5},
{"id": 2, "name": "Item 2", "price": 20.0},
]
return {"message": "Items retrieved successfully", "items": fake_items}
위의 코드는 FastAPI와 Pydantic을 사용하여 간단한 GET API를 정의합니다. Item 클래스는 개별 아이템의 구조를 정의합니다. ResponseModel 클래스는 API 응답의 구조를 정의합니다. get_items 함수는 아이템 목록을 반환하며, 이때 response_model 파라미터를 사용해 응답 모델을 정의합니다. 이는 FastAPI가 자동으로 JSON 응답을 생성하고 문서화를 제공하는 데 도움을 줍니다.
4. 데이터 검증
Pydantic을 사용하면 데이터 검증을 쉽게 수행할 수 있습니다. 모델 정의 시 타입 힌트를 추가하면 FastAPI는 이 정보를 활용하여 API 요청을 검증합니다. 요청 데이터가 유효하지 않으면 FastAPI는 적절한 오류 메시지를 반환합니다.
4.1 요청 데이터 검증 예제
아래는 POST 요청으로 아이템을 추가하는 API의 예제입니다.
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List
app = FastAPI()
class Item(BaseModel):
id: int
name: str
price: float
items = []
@app.post("/items/", response_model=Item)
async def create_item(item: Item):
for existing_item in items:
if existing_item.id == item.id:
raise HTTPException(status_code=400, detail="Item with this ID already exists.")
items.append(item)
return item
위의 코드는 POST 요청을 통해 새로운 아이템을 추가하는 API를 정의합니다. Item이 이미 존재하는지 확인하는 로직을 추가하여 데이터 유효성을 관리합니다. FastAPI는 자동으로 요청(body)을 Item 타입으로 변환하고, 타입 검증을 수행합니다.
5. 자동 문서화
FastAPI는 OpenAPI 스펙에 따라 API 문서를 자동으로 생성합니다. 이 문서에는 모든 엔드포인트, 요청 및 응답 모델이 나열되며, 사용자 친화적인 UI를 제공합니다. FastAPI의 자동화된 문서화 기능은 API의 사용성을 극대화하고, 개발자가 API를 보다 쉽게 이해하도록 도와줍니다.
5.1 Swagger UI와 ReDoc
FastAPI는 기본적으로 Swagger UI와 ReDoc을 지원합니다. 브라우저에서 http://localhost:8000/docs에 접근하면 Swagger UI를 통해 API 문서를 볼 수 있습니다. /redoc 경로를 통해 ReDoc을 사용할 수도 있습니다. 이 문서들은 API의 모든 엔드포인트, 파라미터, 데이터 모델에 대한 정보를 제공합니다.
6. 실전 예제 – 간단한 블로그 API
이제 FastAPI의 타입 정의와 스키마의 강력함을 실제로 구현해보겠습니다. 간단한 블로그 API를 구축하고, 포스트 및 댓글을 관리하는 기능을 추가해보겠습니다.
6.1 블로그 모델 정의
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List
app = FastAPI()
class Comment(BaseModel):
username: str
content: str
class Post(BaseModel):
id: int
title: str
content: str
comments: List[Comment] = []
posts = []
@app.post("/posts/", response_model=Post)
async def create_post(post: Post):
for existing_post in posts:
if existing_post.id == post.id:
raise HTTPException(status_code=400, detail="Post with this ID already exists.")
posts.append(post)
return post
@app.get("/posts/", response_model=List[Post])
async def get_posts():
return posts
위의 코드는 블로그 포스트와 댓글을 정의하는 모델을 생성합니다. 블로그 API에는 포스트를 생성하고 조회하는 엔드포인트가 포함되어 있습니다. create_post 함수는 포스트 객체를 리스트에 추가하고, 중복 ID를 처리하기 위해 오류 처리를 수행합니다.
7. 결론
FastAPI는 빠르고 간편한 API 구축을 위한 강력한 도구입니다. Pydantic을 활용한 타입 정의와 스키마 관리 기능은 API의 안정성 및 문서화의 질을 높입니다. 이러한 기능들은 개발자가 보다 안전하고 효율적인 API를 설계할 수 있도록 도와줍니다.
본 글에서는 FastAPI의 기본 개념과 함께 스키마와 타입 정의의 중요성을 설명하였습니다. 실전 예제를 통해 API를 작성하는 과정에서 발생하는 여러 가지 상황을 다루었습니다. FastAPI의 도구들을 사용하면 API 개발이 더욱 효율적이고 즐거운 경험이 될 것입니다.