[작성자:] root

소개

FastAPI는 현대적인 웹 API를 빠르고 쉽게 개발할 수 있도록 돕는 파이썬 기반의 프레임워크입니다.
비동기 프로그래밍을 지원하여 높은 성능을 제공하며, 부트스트랩이 쉬운 문서화 지원이 특징입니다.
GCP(Google Cloud Platform)는 다양한 클라우드 서비스와 도구를 제공하는 구글의 플랫폼으로, FastAPI 애플리케이션을
배포하기에 적합한 환경입니다. 본 블로그 포스트에서는 FastAPI 서버를 개발하고 이를 GCP에 배포하기 위해 필요한
GCP 계정을 만드는 방법에 대해 자세히 설명합니다.

1. GCP 계정 생성하기

GCP 서비스를 사용하기 위해서는 먼저 Google 계정을 생성해야 하며, 이후 GCP에 로그인하여 계정을 생성할 수 있습니다.

Step 1: Google 계정 만들기

GCP에 접근하기 위해서는 Google 계정이 필요합니다. Google 계정이 없는 경우, [Google 계정 만들기](https://accounts.google.com/signup) 페이지를 방문하여 계정을 생성하세요.
계정 생성 후에는 이메일 인증을 완료해야 합니다.

Step 2: GCP에 로그인하기

Google 계정을 생성한 후, [GCP 콘솔](https://console.cloud.google.com/)에 로그인합니다.
GCP의 대시보드에 접근할 수 있습니다.

Step 3: GCP 프로젝트 생성하기

GCP 콘솔에 로그인한 후, 새로운 프로젝트를 생성해야 합니다. 상단의 드롭다운 메뉴에서 “프로젝트 만들기”를 클릭하여
프로젝트 이름을 입력하고 “만들기” 버튼을 클릭합니다.

Step 4: GCP 무료 사용 등록하기

GCP는 새 사용자에게 90일 동안 사용할 수 있는 무료 크레딧을 제공합니다.
이를 통해 다양한 GCP 서비스를 사용해 볼 수 있습니다. GCP에 가입할 때 무료 사용등록 절차를 따라야 합니다.

2. FastAPI 프로젝트 개발하기

GCP 계정을 생성하고 프로젝트를 만들었다면, 본격적으로 FastAPI 프로젝트를 시작해 보겠습니다.
FastAPI는 Python의 async/await 문법을 활용하여 비동기 처리를 지원합니다.
아래는 간단한 FastAPI 애플리케이션을 만드는 방법입니다.

Step 1: 환경 설정

FastAPI를 설치하기 위해서는 Python과 pip가 필요합니다. Python 3.6 이상이 설치되어 있어야 하며, 아래의 명령어로
FastAPI 및 Uvicorn 서버를 설치합니다.

pip install fastapi uvicorn

Step 2: FastAPI 애플리케이션 작성

간단한 Hello World API를 작성해 보겠습니다. 아래의 코드를 app.py 파일에 저장하세요.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"Hello": "World"}
            

Step 3: 애플리케이션 실행하기

아래의 명령어를 통해 FastAPI 애플리케이션을 로컬에서 실행할 수 있습니다.

uvicorn app:app --reload

로컬에서 실행하면, http://127.0.0.1:8000/docs에서 Swagger UI를 통해 API를 테스트할 수 있습니다.

3. FastAPI 애플리케이션 GCP에 배포하기

이제 FastAPI 애플리케이션을 GCP에 배포하는 방법을 알아보겠습니다. GCP의 Cloud Run 서비스를 사용하여
컨테이너화된 FastAPI 애플리케이션을 쉽게 배포할 수 있습니다.

Step 1: Dockerfile 작성하기

FastAPI 애플리케이션을 Docker 이미지를 생성하기 위해 Dockerfile을 작성합니다. 아래의 내용을 가진 Dockerfile을 생성하세요.

# Dockerfile

FROM python:3.9

WORKDIR /app

COPY . .

RUN pip install fastapi uvicorn

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"]
            

Step 2: Docker 이미지 빌드하기

아래의 명령어를 통해 Docker 이미지를 빌드합니다.

docker build -t fastapi-gcp .

Step 3: Google Container Registry에 이미지 푸시하기

Google Container Registry에 로그인하고 빌드한 이미지를 푸시합니다.

docker tag fastapi-gcp gcr.io/[PROJECT-ID]/fastapi-gcp

docker push gcr.io/[PROJECT-ID]/fastapi-gcp

Step 4: Cloud Run을 통해 애플리케이션 배포하기

GCP 콘솔에서 Cloud Run을 선택하고 “배포”를 클릭합니다.
이미지 URL에 위의 GCR URL을 입력하고 배포를 완료합니다.

배포가 완료된 후 제공된 URL로 FastAPI 애플리케이션에 접근할 수 있습니다.

결론

본 포스트에서는 FastAPI 서버개발과 GCP 계정 작성, 그리고 이를 GCP에 배포하는 과정에 대해 알아보았습니다.
FastAPI를 사용하면 웹 API를 빠르고 쉽게 개발할 수 있으며, GCP는 이러한 애플리케이션을 클라우드에서 손쉽게 호스팅할 수 있는
강력한 플랫폼입니다. 여러분의 프로젝트에 FastAPI와 GCP를 활용해 보세요!

소개

FastAPI는 Python기반의 현대적인 웹 프레임워크로, 비동기 프로그래밍을 지원하고 자동 생성된 API 문서와 유효성 검사를 제공합니다.
본 글에서는 FastAPI와 SQLAlchemy를 사용하여 데이터베이스와 연동하는 방법에 대해 자세히 알아보겠습니다.

FastAPI와 SQLAlchemy 개요

SQLAlchemy는 Python용 SQL 툴킷이자 Object Relational Mapper(ORM)이다.
ORM은 데이터를 클래스로 표현하고, 데이터베이스의 테이블을 객체로 매핑하여 SQL 쿼리를 객체지향적으로 처리할 수 있게 해준다.
FastAPI는 이러한 SQLAlchemy와 잘 통합되어 강력한 RESTful API를 쉽게 구축할 수 있도록 지원한다.

필요한 패키지 설치하기

pip install fastapi uvicorn sqlalchemy databases

프로젝트 구조

이번 예제에서는 다음과 같은 파일 구조를 사용할 것입니다:

    project/
    ├── main.py
    ├── models.py
    ├── database.py
    └── schemas.py
    

1. 데이터베이스 설정

이제 데이터베이스에 연결하기 위한 설정을 해보겠습니다.

database.py

    from sqlalchemy import create_engine, MetaData
    from sqlalchemy.ext.declarative import declarative_base
    from sqlalchemy.orm import sessionmaker

    # 데이터베이스 URL 설정
    DATABASE_URL = "sqlite:///./test.db"  # SQLite 데이터베이스 사용

    # 데이터베이스 엔진을 생성
    engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})

    # 세션을 설정
    SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

    # 기본 클래스 생성
    Base = declarative_base()

    # 데이터베이스 메타데이터
    metadata = MetaData()
    

2. 모델 정의하기

이제 SQLAlchemy 모델을 정의할 차례입니다. 모델은 데이터베이스의 테이블 구조를 정의한 것입니다.

models.py

    from sqlalchemy import Column, Integer, String
    from database import Base

    class User(Base):
        __tablename__ = "users"  # 테이블 이름

        id = Column(Integer, primary_key=True, index=True)  # ID 필드
        name = Column(String, index=True)  # Name 필드
        email = Column(String, unique=True, index=True)  # Email 필드
    

3. Pydantic 스키마 생성하기

FastAPI는 데이터 유효성 검사 및 직렬화를 위해 Pydantic을 사용합니다. 우리는 요청 및 응답에 대한 스키마를 생성해야 합니다.

schemas.py

    from pydantic import BaseModel
    from typing import Optional

    class UserBase(BaseModel):
        name: str
        email: str

    class UserCreate(UserBase):
        pass

    class User(UserBase):
        id: int

        class Config:
            orm_mode = True  # ORM 모드를 활성화
    

4. FastAPI 애플리케이션 생성하기

이제 FastAPI 애플리케이션을 설정할 시간입니다. 우리는 CRUD(Create, Read, Update, Delete) 작업을 구현할 것입니다.

main.py

    from fastapi import FastAPI, Depends, HTTPException
    from sqlalchemy.orm import Session
    from database import SessionLocal, engine
    from models import User, Base
    from schemas import User, UserCreate

    # 데이터베이스 테이블 생성
    Base.metadata.create_all(bind=engine)

    app = FastAPI()

    # 데이터베이스 세션을 가져오는 의존성
    def get_db():
        db = SessionLocal()
        try:
            yield db
        finally:
            db.close()

    @app.post("/users/", response_model=User)
    def create_user(user: UserCreate, db: Session = Depends(get_db)):
        db_user = User(name=user.name, email=user.email)
        db.add(db_user)
        db.commit()
        db.refresh(db_user)
        return db_user

    @app.get("/users/{user_id}", response_model=User)
    def read_user(user_id: int, db: Session = Depends(get_db)):
        user = db.query(User).filter(User.id == user_id).first()
        if user is None:
            raise HTTPException(status_code=404, detail="User not found")
        return user

    @app.get("/users/", response_model=list[User])
    def read_users(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
        users = db.query(User).offset(skip).limit(limit).all()
        return users

    @app.put("/users/{user_id}", response_model=User)
    def update_user(user_id: int, user: UserCreate, db: Session = Depends(get_db)):
        db_user = db.query(User).filter(User.id == user_id).first()
        if db_user is None:
            raise HTTPException(status_code=404, detail="User not found")
        db_user.name = user.name
        db_user.email = user.email
        db.commit()
        db.refresh(db_user)
        return db_user

    @app.delete("/users/{user_id}")
    def delete_user(user_id: int, db: Session = Depends(get_db)):
        db_user = db.query(User).filter(User.id == user_id).first()
        if db_user is None:
            raise HTTPException(status_code=404, detail="User not found")
        db.delete(db_user)
        db.commit()
        return {"message": "User deleted"}
    

5. 애플리케이션 실행하기

이제 모든 설정이 완료되었습니다. 아래 명령어로 FastAPI 애플리케이션을 실행할 수 있습니다.

uvicorn main:app --reload

6. API 테스트하기

API가 성공적으로 실행되면, 브라우저에서 http://127.0.0.1:8000/docs로 이동하여 Swagger UI에서 API를 테스트할 수 있습니다.

예제 요청

    POST /users/
    {
        "name": "Alice",
        "email": "alice@example.com"
    }
    

성공적으로 생성되면 새 사용자 ID가 포함된 응답을 받을 수 있습니다:

    {
        "id": 1,
        "name": "Alice",
        "email": "alice@example.com"
    }
    

결론

이번 글에서는 FastAPI와 SQLAlchemy를 이용하여 간단한 사용자 관리 API를 구축하는 방법을 알아보았습니다.
FastAPI는 직관적인 문법과 비동기 처리 덕분에 신속한 개발이 가능하며, SQLAlchemy와의 통합 덕분에 강력한 데이터베이스 작업을 손쉽게 수행할 수 있습니다.
이를 통해 여러분도 멋진 백엔드 애플리케이션을 개발할 수 있게 되기를 바랍니다.

더 알아보세요

FastAPI와 SQLAlchemy에 대해 더 깊이 있는 정보가 필요하다면 그들의 공식 문서를 참고하시길 권장합니다.

• FastAPI 문서
• SQLAlchemy 문서

FastAPI는 현대적인 웹 프레임워크로, Python으로 작성된 비동기 웹 애플리케이션을 구축하는 데 매우 유용합니다. 특히 RESTful API와 GraphQL API를 손쉽게 구현할 수 있습니다. 이 글에서는 FastAPI로 두 가지 API를 통합하여 사용하는 방법에 대해 자세히 설명하겠습니다.

1. FastAPI란?

FastAPI는 Python 3.6 이상에서 사용할 수 있는 비동기 웹 프레임워크입니다. 자동 문서화, 데이터 유효성 검사 등에 강력한 기능을 가지고 있습니다. 또한, Starlette를 기반으로 하여 높은 성능과 비동기 작업을 지원합니다.

2. REST API와 GraphQL API의 차이

REST API는 자원에 대한 CRUD(Create, Read, Update, Delete) 작업을 수행하는데, 각 자원은 고유한 URI를 가지고 있습니다. 반면, GraphQL API는 클라이언트가 필요한 데이터를 명확하게 요청할 수 있는 쿼리 언어를 제공합니다. GraphQL을 사용하면 데이터 전송량을 줄이고, 클라이언트에서 원하는 형식으로 데이터를 요청할 수 있어 효율적입니다.

2.1 REST API의 예

GET /users : 모든 사용자 정보 가져오기
POST /users : 새로운 사용자 추가하기
GET /users/1 : 특정 사용자 정보 가져오기
PUT /users/1 : 특정 사용자 정보 수정하기
DELETE /users/1 : 특정 사용자 삭제하기
    

2.2 GraphQL의 예

query {
  users {
    id
    name
  }
}
mutation {
  createUser(name: "Alice") {
    id
    name
  }
}
    

3. FastAPI 설치

FastAPI를 사용하기 위해 필요한 패키지를 설치합니다. 먼저 Python과 pip가 설치되어 있는지 확인합니다. 다음 명령어를 사용하여 FastAPI와 Uvicorn을 설치할 수 있습니다.

pip install fastapi uvicorn

4. FastAPI 프로젝트 구조

FastAPI 프로젝트 구조는 아래와 같이 설정할 수 있습니다.

my_fastapi_project/
    ├── main.py
    ├── models.py
    ├── schemas.py
    ├── database.py
    └── graphql.py
    

5. FastAPI로 REST API 구현하기

이제 FastAPI를 사용하여 REST API를 구현해보겠습니다. 먼저 models.py 파일에서 데이터 모델을 정의합니다.

from pydantic import BaseModel
from typing import List

class User(BaseModel):
    id: int
    name: str

5.1 데이터베이스 설정

데이터베이스 접속을 위해 아래와 같은 database.py 파일을 만듭니다. SQLAlchemy를 사용하여 데이터베이스와 상호작용합니다.

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

SQLALCHEMY_DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

class UserDB(Base):
    __tablename__ = "users"
    
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)

Base.metadata.create_all(bind=engine)

5.2 REST API 엔드포인트 만들기

이제 main.py 파일에 REST API 엔드포인트를 작성합니다.

from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
from database import SessionLocal, UserDB, engine
from models import User

app = FastAPI()

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.post("/users/", response_model=User)
def create_user(user: User, db: Session = Depends(get_db)):
    db_user = UserDB(name=user.name)
    db.add(db_user)
    db.commit()
    db.refresh(db_user)
    return db_user

@app.get("/users/", response_model=List[User])
def read_users(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
    users = db.query(UserDB).offset(skip).limit(limit).all()
    return users

6. FastAPI로 GraphQL API 구현하기

이제 GraphQL API를 구현해보겠습니다. graphql.py 파일에서 GraphQL 스키마를 정의합니다.

from fastapi import FastAPI
from fastapi.openapi.docs import get_swagger_ui_html
from graphene import ObjectType, String, Schema, Field, List
from models import User, UserDB
from database import SessionLocal

class UserType(ObjectType):
    id = String()
    name = String()

class Query(ObjectType):
    users = List(UserType)

    def resolve_users(self, info):
        db = SessionLocal()
        return db.query(UserDB).all()

schema = Schema(query=Query)

app = FastAPI()

@app.get("/graphql/")
async def graphql_endpoint():
    return await Query().execute()

7. 두 API 통합하기

이제 두 가지 API를 통합할 시간입니다. 다음과 같이 FastAPI의 라우터와 GraphQL endpoint를 함께 사용할 수 있습니다.

from fastapi import FastAPI
from fastapi_graphql import GraphQLRouter
from database import Base, engine
from graphql import schema

app = FastAPI()

Base.metadata.create_all(bind=engine)

app.include_router(GraphQLRouter(schema=schema), prefix="/graphql")

# 기존 REST API 엔드포인트 코드...

8. 서버 실행하기

마지막으로, Uvicorn을 사용하여 FastAPI 서버를 실행합니다. 아래 명령어로 서버를 실행할 수 있습니다.

uvicorn main:app --reload

9. API 테스트

서버가 실행되면 http://127.0.0.1:8000/docs 주소에서 Swagger UI를 통해 REST API를 테스트할 수 있습니다. GraphQL API는 http://127.0.0.1:8000/graphql/에서 테스트할 수 있습니다.

10. 결론

FastAPI를 사용하면 REST API와 GraphQL API를 손쉽게 구축하고 통합할 수 있습니다. 이번 튜토리얼을 통해 두 가지 API 유형을 함께 사용하는 방법을 배웠습니다. 이를 통해 개발자는 필요에 따라 API를 선택할 수 있으며, 클라이언트의 요구를 충족할 수 있게 됩니다.

추가적인 질문이나 궁금증이 있다면 댓글로 남겨주시면 답변해드리겠습니다!

현대의 웹 애플리케이션 개발에서는 API와 그 문서화가 매우 중요합니다. FastAPI는
파이썬으로 제작된 웹 프레임워크로, 높은 성능과 사용의 용이성 덕분에 많은 개발자들 사이에서 각광받고 있습니다.
본 글에서는 FastAPI의 자동 문서화 기능에 대해 다룰 것입니다. 특히, Swagger UI와 ReDoc을 사용하여
FastAPI 애플리케이션의 API 문서화를 어떻게 수행하는지에 대해 자세히 알아보겠습니다.

1. FastAPI 소개

FastAPI는 Starlette와 Pydantic을 기반으로 구축된 현대적인 웹 프레임워크로,
RESTful API를 빠르고 쉽게 개발할 수 있도록 설계되었습니다. FastAPI의 주요 특징으로는
매우 빠른 성능, 자동적인 데이터 검증 및 직렬화, 그리고 멀티스레드를 지원하는 비동기 기능 등이 있습니다.

1.1 FastAPI의 특징

• 성능: Starlette를 기반으로 하여 비동기 처리를 통해 높은 성능을 자랑합니다.
• 자동 문서화: Swagger UI와 ReDoc을 통해 API 문서화를 자동으로 수행합니다.
• 유효성 검사: Pydantic을 사용하여 데이터 검증을 쉽게 처리할 수 있습니다.
• 간편한 라우팅 및 경로 매핑: 직관적인 경로 매핑 기능을 제공합니다.

2. FastAPI의 설치

FastAPI를 설치하기 위해서는 먼저 Python이 설치되어 있어야 합니다. 이후 다음의 명령어로 FastAPI와
Uvicorn(ASGI 서버)을 설치할 수 있습니다.

pip install fastapi uvicorn

3. FastAPI 애플리케이션 기본 설정

FastAPI로 애플리케이션을 생성하고 기본적인 API를 설정하는 방법을 알아보겠습니다.
아래는 기본적인 FastAPI 애플리케이션의 예제 코드입니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

위 코드는 기본적인 FastAPI 애플리케이션을 생성하며, 루트 경로(‘/’)와
파라미터가 있는 경로(‘/items/{item_id}’)를 정의하고 있습니다.
이를 실행하기 위해서는 다음과 같은 명령어를 사용할 수 있습니다.

uvicorn main:app --reload

위의 명령어에서 ‘main’은 파일 이름이며, ‘app’은 FastAPI 인스턴스입니다.
–reload 옵션을 통해 코드 변경 시 서버를 자동으로 재시작하도록 설정할 수 있습니다.

4. FastAPI의 자동 문서화 기능

FastAPI는 Swagger UI와 ReDoc을 사용하여 API 문서화를 자동으로 수행합니다.
이러한 기능은 개발자가 API Endpoint를 정의할 때, FastAPI가 자동으로
해당 API에 대한 문서를 생성하도록 합니다.

4.1 Swagger UI

FastAPI에서 Swagger UI를 사용하는 것은 매우 간단합니다.
애플리케이션을 실행하면 기본적으로 ‘/docs’ 경로에서 Swagger UI에 접근할 수 있습니다.
Swagger UI는 API의 요청 방식(HTTP 메서드, URL 등), 요청/응답의 데이터 구조,
예제 등을 포함하여 직관적으로 API를 테스트할 수 있는 인터페이스를 제공합니다.

Swagger UI 예제

FastAPI 애플리케이션을 실행한 후, 웹 브라우저에서 ‘http://localhost:8000/docs’를
열어보세요. 귀하의 API Endpoint에 대한 문서가 자동으로 생성된 것을 확인할 수 있습니다.
예를 들어 위에서 설정한 루트 경로(‘/’)와 ‘/items/{item_id}’ 경로가
Swagger UI에서 나열되고, 각 경로에 대한 요청을 보낼 수 있는 버튼이 제공됩니다.

4.2 ReDoc

FastAPI는 또한 ReDoc을 통해 API 문서화를 지원합니다.
ReDoc은 깔끔하고 현대적인 디자인으로 복잡한 API를 쉽게 탐색할 수 있도록 도와줍니다.
ReDoc 문서는 ‘/redoc’ 경로에서 확인할 수 있습니다.

ReDoc 예제

FastAPI 애플리케이션을 실행한 후, 웹 브라우저에서 ‘http://localhost:8000/redoc’를
열어보세요. ReDoc으로 생성된 API 문서를 확인할 수 있습니다.
각 API Endpoint에 대한 설명과 요청/응답 모델을 간결하게 보여줍니다.

5. FastAPI의 문서화에 대한 추가적인 기능

FastAPI는 문서화 기능을 강화하기 위한 여러 가지 옵션을 제공합니다.
예를 들어, API 문서화 시에 사용할 제목, 설명 및 버전 정보를 설정할 수 있습니다.

예제 코드

from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="API 설명을 여기에 적습니다.",
    version="1.0.0",
)

@app.get("/")
def read_root():
    return {"Hello": "World"}

위와 같이 FastAPI 인스턴스를 생성할 때, title, description, version 등의
매개변수를 지정할 수 있습니다. 이렇게 하면 Swagger UI와 ReDoc에 설정한 값이
자동으로 반영됩니다.

6. 의존성과 보안 기능을 활용한 문서화

FastAPI는 API 문서화를 단순화하는 것만이 아니라, 의존성 주입(Dependency Injection)와 보안
기능을 통해 API의 복잡한 구조를 관리하는 데도 유용합니다. 예를 들어,
인증이 필요한 API Endpoint의 경우 FastAPI는 이러한 기능을 문서화하는 데 있어서
유용한 정보를 제공합니다.

예제 코드

from fastapi import FastAPI, Depends

app = FastAPI()

def fake_authenticate(username: str, password: str):
    if username == "admin" and password == "secret":
        return True
    return False

@app.get("/secure-data/")
def get_secure_data(authenticated: bool = Depends(fake_authenticate)):
    return {"data": "This is secured data"}

위 예제를 실행할 경우 ‘/secure-data/’ Endpoint는 ‘fake_authenticate’ 함수를 통해
인증을 요구합니다. Swagger UI에서는 이 Endpoint에 대해 인증 요구 사항이
명시적으로 표시될 것입니다.

7. 결론

FastAPI는 훌륭한 자동 문서화 기능을 제공하여 API 개발을 보다 쉽게 만들어 줍니다.
Swagger UI와 ReDoc을 통해 API 문서를 자동으로 생성할 수 있는 기능은 개발자에게 큰
시간을 절약하게 하며, 적시에 문서화된 API를 제공할 수 있습니다.
또한 FastAPI의 다양한 기능을 통해 애플리케이션의 안정성과 보안성을 높일 수 있습니다.

FastAPI를 사용한 API 개발의 모든 과정을 이해하는 데 도움이 되었기를 바랍니다.
앞으로도 FastAPI를 활용하여 더 나은 웹 애플리케이션을 개발해 보세요!

FastAPI는 Python으로 작성된 현대적인 웹 프레임워크로, 빠른 개발과 성능을 목표로 하고 있습니다. 이 블로그 포스트에서는 FastAPI에서 스키마를 정의하고 이를 통해 응답을 설정하는 방법에 대해 자세히 설명하도록 하겠습니다. 우리는 여기에 여러 예제와 함께 설명할 것이며, 명확한 이해를 돕기 위해 단계적으로 진행하겠습니다.

FastAPI란?

FastAPI는 다음과 같은 주요 특징을 가지고 있습니다:

• 자동 생성된 OpenAPI 문서
• 유효성 검사를 통한 데이터 검증
• 비동기 지원으로 높은 성능
• 모든 매개변수의 자동 문서화

FastAPI 설치

FastAPI를 시작하기 위해서는 먼저 FastAPI와 Uvicorn을 설치해야 합니다. Uvicorn은 ASGI 서버로 FastAPI 애플리케이션을 실행하는 데 사용됩니다. 아래와 같이 설치할 수 있습니다:

pip install fastapi uvicorn

응답 스키마 정의

FastAPI는 Pydantic을 통해 데이터 유효성 검사와 직렬화를 처리합니다. Pydantic 모델을 사용하면 API의 데이터 모델을 정의할 수 있습니다. 이를 통해 클라이언트가 요청한 데이터를 검증하고, 서버가 보낼 응답 형태를 정의할 수 있습니다.

Pydantic 모델 생성

Pydantic 모델을 생성하는 방법에 대해 살펴보겠습니다. 아래는 간단한 Pydantic 모델을 정의하는 예제입니다:

from pydantic import BaseModel

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

위의 Item 클래스는 name, description, price, 그리고 tax 필드를 포함하고 있습니다. description와 tax는 기본값으로 None을 설정하였으므로 선택적 필드입니다. 이제 이 모델을 사용하여 FastAPI 라우트를 정의해 보겠습니다.

FastAPI에서 응답 정의

FastAPI에서 정의한 Pydantic 모델을 응답 스키마로 활용하는 방법을 설명하겠습니다. 아래는 FastAPI와 Pydantic을 사용한 간단한 API 예제입니다:

from fastapi import FastAPI

app = FastAPI()

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

위의 예제에서는 /items/ 엔드포인트를 통해 아이템을 생성하는 API를 정의하였습니다. 사용자가 요청한 아이템 데이터는 Pydantic 모델인 Item을 기준으로 검증됩니다. 요청이 성공적으로 처리되면, 동일한 아이템 데이터가 응답으로 반환됩니다.

응답 타입 정의

FastAPI에서는 응답의 타입을 정의하여 클라이언트에게 어떤 형식의 데이터를 보낼 것인지 명확히 알릴 수 있습니다. 이는 API의 가독성을 높이고, 클라이언트가 올바르게 요청을 할 수 있도록 돕습니다.

응답 모델 사용하기

응답 모델은 위에서 정의한 Pydantic 모델을 쉽게 활용할 수 있습니다. 여기서는 약간 더 복잡한 예제를 통해 응답 타입을 정의하는 방법을 알아보겠습니다:

from typing import List

class ItemResponse(BaseModel):
    items: List[Item]
    total: int

@app.get("/items/", response_model=ItemResponse)
async def read_items(skip: int = 0, limit: int = 10):
    # 여기서 실제 데이터베이스 쿼리를 수행하겠지만, 예제로 일부 더미 데이터를 반환합니다.
    fake_items = [Item(name="Item 1", price=100.0), Item(name="Item 2", price=200.0)]
    return ItemResponse(items=fake_items, total=len(fake_items))

위의 예제는 /items/ 엔드포인트를 통해 아이템 리스트와 총 개수를 반환합니다. ItemResponse 모델은 items 필드와 total 필드를 포함하고 있으며, 데이터를 리스트와 정수 형태로 묶어서 보냅니다.

응답 JSON 예제

위의 예제를 통해 API를 호출하면 다음과 같은 JSON 응답을 얻을 수 있습니다:

{
    "items": [
        {"name": "Item 1", "description": null, "price": 100.0, "tax": null},
        {"name": "Item 2", "description": null, "price": 200.0, "tax": null}
    ],
    "total": 2
}

여기서 클라이언트는 요청한 API에서 어떤 형태의 데이터가 반환될지를 예측할 수 있으며, 이는 개발자와 사용자가 더 나은 대화를 할 수 있도록 돕습니다.

오류 응답 처리

FastAPI에서는 정의된 스키마에 맞지 않는 요청에 대해 자동으로 오류를 처리합니다. 사용자가 잘못된 데이터를 보낼 경우, FastAPI는 422 Unprocessable Entity 오류를 반환하며, 어떤 필드가 잘못되었는지에 대한 정보를 제공합니다.

POST /items/
{
    "name": "Item 1",
    "price": "Not a number"  # 이 필드는 숫자가 필요합니다.
}

이와 같은 경우 FastAPI는 다음과 같은 오류 응답을 생성합니다:

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

결론

이 블로그 포스트에서는 FastAPI에서 스키마를 정의하고, 이를 통해 API의 응답 타입을 설정하는 방법에 대해 자세히 살펴보았습니다. Pydantic 모델을 사용하여 데이터 구조를 정의하고, 이를 FastAPI에 통합하여 강력한 API를 만들 수 있음을 확인하였습니다. 이러한 접근은 데이터의 무결성과 API의 명료성을 보장하는 데 큰 도움이 됩니다.

FastAPI를 통해 더 나은 웹 서비스를 개발할 수 있기를 바랍니다. 추가적인 질문이 있다면 언제든지 댓글 달아 주시기 바랍니다!