• 목차
• 🟥 Epic 1 — Task 3
  • 🚀 FastAPI 기본 서버 구축
    • 📌 작업 개요
    • 🎯 작업 목적
    • 🛠️ 진행 내용
      • 🗂️ 1. FastAPI 엔트리포인트(main.py) 작성
      • 🗂️ 2. uvicorn 실행 테스트
      • 🗂️ 3. test_main.http 파일을 활용한 API 테스트
      • 🗂️ 4. 라우터 구조 분리 준비
      • 🗂️ 5. FastAPI 자동 문서 확인
    • 📌 산출물

🟥 Epic 1 — Task 3¶

🚀 FastAPI 기본 서버 구축¶

📌 작업 개요¶

• FastAPI 기반 mgmt 서버의 첫 실행 환경을 구축하는 단계이다.
• 프로젝트가 정상적으로 동작하는지 확인하기 위해 핵심 엔트리포인트(main.py)를 작성하고,
• 기본적인 API 엔드포인트(/ping)를 구현하여 서버가 정상적으로 응답하는지 검증한다.

이 작업은 이후 모든 기능 개발의 기반이 되는 최초 실행 환경 구성 단계이다.

🎯 작업 목적¶

• FastAPI 서버가 정상적으로 실행되는지 확인한다.

• uvicorn을 통해 개발 환경에서 서버를 구동할 수 있도록 한다.

• /ping API를 구현하여 기본적인 요청/응답 흐름을 검증한다.

• PyCharm 디버그 환경과 test_main.http 파일을 활용해 API 테스트 기반을 마련한다.

🛠️ 진행 내용¶

🗂️ 1. FastAPI 엔트리포인트(main.py) 작성¶

FastAPI 서버의 시작점이 되는 main.py 파일을 생성하고,
FastAPI 인스턴스를 초기화한다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/ping")
def ping():
    return {"msg": "pong"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("app.main:app", host="127.0.0.1", port=8000, reload=True)

• reload=True는 개발 편의성 향상

• 디버깅 시에는 reload=False로 변경 가능

🗂️ 2. uvicorn 실행 테스트¶

• PyCharm에서 Run/Debug Configuration을 생성하여 FastAPI 서버가 정상적으로 실행되는지 확인한다.

• 실행 후 브라우저에서

👉 http://127.0.0.1:8000/ping

응답이 { "msg": "pong" } 이면 정상

🗂️ 3. test_main.http 파일을 활용한 API 테스트¶

• PyCharm이 자동 생성한 .http 파일을 활용하여 FastAPI 엔드포인트를 직접 호출해본다.

예시:

### Ping Test
GET http://127.0.0.1:8000/ping
Accept: application/json

• Send Request 버튼 클릭

• 응답이 정상적으로 표시되는지 확인

🗂️ 4. 라우터 구조 분리 준비¶

향후 /server, /control, /ssh 등 기능별 라우터를 분리하기 위해
app/routers/health.py 파일을 생성하고 /ping API를 이동할 준비를 한다.

예시:

from fastapi import APIRouter

router = APIRouter()

@router.get("/ping")
def ping():
    return {"msg": "pong"}

그리고 main.py에서 라우터를 등록한다:

from fastapi import FastAPI
from app.routers import health

app = FastAPI()
app.include_router(health.router)

🗂️ 5. FastAPI 자동 문서 확인¶

• FastAPI는 기본적으로 자동 문서를 제공한다.

• Swagger UI

  👉 http://127.0.0.1:8000/docs

• ReDoc

  👉 http://127.0.0.1:8000/redoc

여기서 /ping API가 정상적으로 표시되는지 확인한다.

📌 산출물¶

• FastAPI 엔트리포인트(main.py)

• /ping API 구현

• uvicorn 실행 및 디버그 환경 구성

• test_main.http 테스트 완료

• 라우터 구조 분리 준비 완료

• Swagger/ReDoc 자동 문서 정상 표시