IT 20년차의 복합 비즈니스 도전

이전 1강에서 Swagger TypeScript API의 도입 목적과 커리큘럼을 살펴봤습니다. 이번 2강에서는 개발 환경 세팅과 설치 가이드를 구체적으로 안내합니다. **FastAPI(백엔드)**와 **React(Vite)(프론트엔드)**를 같은 저장소에서 운영한다는 가정 하에, 프로젝트 디렉토리 구성 예시도 함께 제시합니다.

---

1. 전체 프로젝트 디렉토리 구성 예시

아래는 **백엔드(FastAPI)**와 **프론트엔드(React + Vite)**를 모노레포 방식으로 관리하는 기본 예시입니다. 실제 상황에 맞게 유연하게 조정할 수 있습니다.

my-project/
├── backend/
│   ├── main.py
│   ├── requirements.txt
│   └── ...(FastAPI 관련 파일들)
├── frontend/
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts
│   ├── public/
│   └── src/
│       ├── App.tsx
│       ├── main.tsx
│       └── ...(React 컴포넌트들)
├── openapi/
│   └── api-spec.yaml (직접 작성 시)
├── .gitignore
├── README.md
└── ...(기타 설정/배포 스크립트)

---

2. 백엔드(FastAPI) 환경 세팅

1) Python 버전 확인

• FastAPI는 Python 3.7 이상을 권장합니다.
• 아래 명령어로 버전을 확인하세요.

python --version

2) 가상 환경(venv) 및 FastAPI 설치

cd backend
python -m venv venv
source venv/bin/activate  # Windows에서는 venv\Scripts\activate
pip install fastapi uvicorn

• FastAPI: Python 프레임워크
• Uvicorn: ASGI 서버, FastAPI 실행 시 권장

3) 기본 서버 실행 테스트

main.py 예시:

from fastapi import FastAPI

app = FastAPI()

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

uvicorn main:app --reload

• 브라우저 확인: http://127.0.0.1:8000/docs에서 Swagger UI 자동 생성 여부를 확인합니다.

주의사항: FastAPI 서버가 정상적으로 동작하는지 먼저 점검하세요. 스펙(/openapi.json)을 불러와야 이후 연동이 수월합니다.

---

3. 프론트엔드(React + Vite) 환경 세팅

1) Node.js 및 NPM 설치

• Node.js 공식 사이트에서 LTS 버전 설치를 권장
• 설치 후 버전 확인: 
• node -v npm -v

2) React + Vite + TypeScript 프로젝트 생성

cd ../
cd frontend
npm create vite@latest . -- --template react-ts
npm install

• --template react-ts: TypeScript 환경으로 React 앱 구성
• 설치 완료 후 프로젝트 구조:

  frontend/
  ├── package.json
  ├── tsconfig.json
  ├── vite.config.ts
  ├── public/
  └── src/
      ├── App.tsx
      ├── main.tsx
      └── ...
  

Tip: npm run dev를 통해 로컬 개발 서버를 실행하고, http://127.0.0.1:5173(기본값)에서 React 앱이 동작하는지 확인하세요.

---

4. Node.js 기반으로 swagger-typescript-api 설치

1) 프로젝트 초기화(백엔드와는 별개)

백엔드 코드와 분리해 클라이언트 생성 로직을 관리하려면 루트 디렉토리나, 혹은 frontend/ 내부에서 작업할 수도 있습니다.

cd frontend
npm init -y
npm install swagger-typescript-api --save-dev

• swagger-typescript-api: OpenAPI 스펙으로부터 TypeScript 클라이언트 코드를 자동 생성하는 핵심 도구

2) CLI 동작 확인

npx swagger-typescript-api --help

• 주요 옵션:
  • --path: OpenAPI 스펙 URL 또는 로컬 파일 경로
  • --output: 생성된 코드가 저장될 폴더
  • --name: 생성된 파일명 지정
  • --axios or --fetch: Axios 또는 Fetch 기반 코드 생성 선택

---

5. 간단한 코드 생성 예시

이제 FastAPI가 띄워진 상태에서 실제 OpenAPI URL(http://127.0.0.1:8000/openapi.json)을 참조해보겠습니다.

npx swagger-typescript-api \
  --path "http://127.0.0.1:8000/openapi.json" \
  --output "./src/api" \
  --name "ApiClient.ts"

• --output "./src/api": 프론트엔드 src 폴더 아래 api 디렉토리에 클라이언트 코드를 저장
• --name "ApiClient.ts": 생성된 파일명을 지정

생성이 완료되면, ApiClient.ts 내부에서 FastAPI가 제공하는 엔드포인트와 데이터 모델을 반영한 함수들이 자동으로 정의되어 있음을 확인할 수 있습니다.

---

6. 정리 및 다음 강의 예고

이번 2강에서는 모노레포 구조를 기반으로 **FastAPI(백엔드)**와 **React(Vite)(프론트엔드)**가 서로 연계될 수 있도록 프로젝트 디렉토리 구성, 개발 환경 세팅, swagger-typescript-api 설치 과정을 다루었습니다.

1. 백엔드: Python 3.7+, FastAPI, Uvicorn 설치 및 기본 서버 테스트
2. 프론트엔드: Node.js + Vite + React + TypeScript 초기화
3. 스펙 기반 자동 코드 생성: swagger-typescript-api를 통해 /openapi.json 참조, 클라이언트 코드 생성

다음 3강에서는 FastAPI Todo 예제를 작성하고, 실제 OpenAPI 스펙을 참고해 클라이언트 코드를 생성하는 과정을 상세히 시연해볼 예정입니다.