[파이썬 심화] FastAPI 구조, Docker 배포방법, OpenAPI 문화활용

FastAPI 기본 구조와 실행 방법

FastAPI는 빠르고 간결한 문법으로 유명한 Python 웹 프레임워크입니다.
Pydantic을 활용한 데이터 검증, 자동 Swagger UI, 비동기 지원이 특징이며, API 서버 제작에 최적화되어 있습니다.

1. FastAPI 설치

pip install fastapi uvicorn

uvicorn은 FastAPI 앱을 실행하기 위한 ASGI 서버입니다.

2. 기본 앱 예제 (main.py)

from fastapi import FastAPI

app = FastAPI()

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

3. 앱 실행

uvicorn main:app --reload

main: 파일명 (main.py)
app: FastAPI 객체 변수명
--reload: 코드 변경 시 자동 반영 (개발용)

4. API 문서 자동 생성

/docs: Swagger UI 자동 제공
/redoc: ReDoc 문서도 자동 제공

FastAPI는 OpenAPI 스펙 기반 문서를 자동으로 생성해주므로 별도 작업 없이도 개발/배포 문서가 완성됩니다.

Docker로 FastAPI 앱 배포하기

1. 프로젝트 구조

myfastapi/
├── main.py
├── requirements.txt
└── Dockerfile

2. requirements.txt

fastapi
uvicorn[standard]

3. Dockerfile

FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

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

4. Docker 이미지 빌드 및 실행

# 이미지 빌드
docker build -t fastapi-app .

# 컨테이너 실행
docker run -d -p 8000:8000 fastapi-app

브라우저에서 http://localhost:8000 접속하면 API가 실행되고,
/docs에서 자동 생성된 Swagger 문서를 확인할 수 있습니다.

5. docker-compose로 환경 통합

version: "3"
services:
  web:
    build: .
    ports:
      - "8000:8000"

docker-compose up --build 명령으로 여러 서비스(DB 등)와 함께 앱을 구성할 수 있습니다.

OpenAPI 문서 활용과 배포 자동화 팁

1. OpenAPI 스키마 확인

/openapi.json

FastAPI는 API 정의 정보를 OpenAPI 3.0 형식으로 JSON 스키마로 제공합니다.
이를 활용해 클라이언트 코드 생성, 문서 배포, 외부 연동이 가능합니다.

2. 프론트엔드 연동용 문서 변환

pip install openapi-typescript-codegen
openapi --input http://localhost:8000/openapi.json --output frontend/api

openapi-typescript-codegen 도구로 프론트엔드 개발자가 사용할 API 호출 코드 자동 생성도 가능합니다.

3. GitHub Actions를 통한 배포 자동화 예시

📁 .github/workflows/deploy.yml

name: FastAPI CI

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v3

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.10'

    - name: Install dependencies
      run: |
        pip install -r requirements.txt

    - name: Test with pytest
      run: |
        pip install pytest
        pytest

    - name: Build Docker image
      run: docker build -t fastapi-app .

    - name: Push to Docker Hub
      run: |
        echo "${{ secrets.DOCKER_PASSWORD }}" | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
        docker tag fastapi-app ${{ secrets.DOCKER_USERNAME }}/fastapi-app:latest
        docker push ${{ secrets.DOCKER_USERNAME }}/fastapi-app:latest

코드 푸시 시 자동으로 테스트 → Docker 이미지 빌드 및 배포가 이루어지는 완전한 CI/CD 구성입니다.

4. FastAPI 앱을 Nginx + HTTPS와 함께 배포하기

Gunicorn + Uvicorn Worker로 WSGI 대신 ASGI 지원
Nginx에서 리버스 프록시 + HTTPS 처리
certbot으로 무료 SSL 인증서 자동 갱신 가능

대규모 서비스에서는 Gunicorn, Nginx, Docker Compose, Let's Encrypt를 함께 구성하여 안정성과 보안을 강화합니다.

FastAPI는 단순한 백엔드 프레임워크가 아니라, 자동 문서화, 타입 기반 유효성 검사, 배포 친화성까지 갖춘 강력한 API 플랫폼입니다. Docker와 GitHub Actions, OpenAPI 문서 활용까지 익히면 실제 운영 가능한 수준의 백엔드 서비스를 손쉽게 구축할 수 있습니다.

프로그래밍 개발자의 지식창고