FastAPI 시작하기

이 장에서는 FastAPI를 설치하고 첫 API를 만들어 개발 서버로 실행하는 과정까지 다룹니다. 자동으로 만들어지는 API 문서를 확인하고, 편집기를 어떻게 설정하면 좋은지도 함께 살펴봅니다.

준비물

FastAPI는 Python 라이브러리이므로 먼저 Python이 설치되어 있어야 합니다. FastAPI는 타입 힌트를 적극적으로 사용하므로, 공식 문서가 지원한다고 밝힌 범위 안의 최신 Python을 쓰는 것이 좋습니다. 터미널에서 버전을 확인합니다.

python --version
# Windows에서 python 명령이 없다면
py --version

가상 환경 만들기

프로젝트마다 의존성을 따로 관리하려면 가상 환경을 씁니다. 프로젝트 폴더를 만들고 그 안에 .venv 가상 환경을 만든 뒤 활성화합니다.

mkdir hello-fastapi
cd hello-fastapi
python -m venv .venv

# macOS · Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

활성화되면 프롬프트 앞에 (.venv)가 붙고, 이후 pip로 설치하는 패키지는 이 폴더 안에만 들어갑니다. 작업을 마칠 때는 deactivate를 실행합니다.

FastAPI 설치

FastAPI는 standard 추가 구성과 함께 설치하는 것을 권합니다. 이렇게 하면 ASGI 서버 Uvicorn, fastapi 명령줄 도구, 테스트에 쓰는 HTTPX, 폼 처리용 python-multipart 같은 자주 쓰는 의존성이 함께 설치됩니다.

pip install "fastapi[standard]"

대괄호가 셸에서 특수 문자로 해석될 수 있으므로 따옴표로 감싸는 것이 안전합니다. 설치한 목록을 고정해 두려면 pip freeze > requirements.txt로 파일을 만들고, 다른 환경에서는 pip install -r requirements.txt로 같은 구성을 재현합니다. uv나 Poetry 같은 도구를 써도 되며, 이때는 pyproject.toml에 의존성을 적습니다.

첫 API 만들기

프로젝트 폴더에 main.py를 만들고 다음 코드를 넣습니다.

from fastapi import FastAPI

app = FastAPI()


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


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

FastAPI()로 만든 app이 애플리케이션 전체를 나타냅니다. @app.get("/")처럼 HTTP 메서드 이름의 데코레이터를 붙인 함수를 경로 작업 함수라고 부릅니다. 함수가 돌려준 딕셔너리, 리스트, Pydantic 모델은 자동으로 JSON 응답으로 바뀝니다.

두 번째 함수에서 {item_id}는 경로 매개변수이고, item_id: int라는 타입 힌트 덕분에 FastAPI가 값을 정수로 변환하고 검증합니다. /items/abc처럼 정수가 아닌 값이 오면 함수는 실행되지 않고 422 오류와 함께 무엇이 잘못됐는지 알려 주는 JSON이 돌아갑니다. 기본값이 있는 q는 ?q=hello 같은 선택적 쿼리 매개변수가 됩니다.

개발 서버 실행

fastapi dev 명령으로 개발 서버를 띄웁니다.

fastapi dev main.py

실행하면 터미널에 서버 주소와 문서 주소, 찾아낸 앱 객체가 표시됩니다. 개발 모드에서는 코드를 저장할 때마다 서버가 자동으로 다시 시작되며, 기본 주소는 http://127.0.0.1:8000입니다. 서버를 멈추려면 Ctrl+C를 누릅니다. 다른 포트를 쓰려면 --port 8080을 붙입니다. 브라우저나 curl로 확인해 봅니다.

curl http://127.0.0.1:8000/
curl "http://127.0.0.1:8000/items/5?q=hello"

자동 API 문서

FastAPI는 코드에서 OpenAPI 스키마를 만들어 두 가지 문서 화면을 기본으로 제공합니다.

/docs에서 엔드포인트를 펼치고 "Try it out"을 누르면 매개변수를 입력해 요청을 보내고 응답을 바로 볼 수 있습니다. 코드를 고치면 문서도 함께 바뀝니다.

편집기 설정

FastAPI는 타입 힌트를 바탕으로 동작하므로 타입 정보를 잘 활용하는 편집기를 쓰면 자동 완성과 오류 표시의 도움을 크게 받습니다.

• VS Code: Microsoft의 Python 확장과 Pylance를 설치하고, 명령 팔레트의 "Python: Select Interpreter"에서 .venv의 Python을 고릅니다.
• PyCharm: 프로젝트 인터프리터로 .venv를 지정하면 FastAPI 코드의 자동 완성과 타입 검사가 동작합니다.
• 서식과 린트에는 Ruff, 정적 타입 검사에는 mypy를 함께 쓰면 좋습니다.

정리

• 가상 환경을 만들고 pip install "fastapi[standard]"로 설치합니다.
• FastAPI() 객체와 @app.get 같은 데코레이터로 경로 작업을 정의합니다.
• fastapi dev main.py로 자동 재시작되는 개발 서버를 띄웁니다.
• /docs와 /redoc에서 자동 생성된 대화형 API 문서를 확인합니다.