FastAPI 시작하기 — Python으로 API 만들기

개발 가이드 / fastapi-quickstart.html

Python으로 자동 문서가 붙는 REST API를 빠르게 만드는 방법을 설치부터 최소 예제까지 정리했습니다.

💬 "Python으로 API를 빠르게 만들려면?"

FastAPI는 Python으로 REST API를 만들 때 쓰는 웹 프레임워크입니다. 함수의 인자·리턴 타입만 적어도 요청 검증과 문서가 자동으로 만들어지는 게 특징입니다. 아래는 공식 문서의 권장 방식(venv + uv/pip)으로 최소 동작까지 가는 절차입니다.

환경 준비

• Python 3.9 이상
• 프로젝트마다 하나의 가상환경 (권장)

설치

공식 문서는 uv로 프로젝트를 만드는 방식을 안내합니다. uv를 쓰지 않는다면 pip로도 동일합니다.

# uv 사용 (공식 문서 방식)
uv init --bare myapi
cd myapi
uv add fastapi "uvicorn[standard]"

# 또는 pip + venv 사용
python3 -m venv .venv
source .venv/bin/activate
pip install fastapi "uvicorn[standard]"

최소 예제

main.py에 다음 내용을 적습니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"message": "hello"}

실행합니다.

uvicorn main:app --reload

브라우저에서 http://127.0.0.1:8000을 열면 JSON이 보이고, http://127.0.0.1:8000/docs에서 자동 생성된 API 문서를 확인할 수 있습니다.

이해해야 할 핵심

• @app.get("/") 같은 데코레이터가 경로를 등록합니다.
• 함수의 인자 타입 힌트가 요청 검증에 사용됩니다. 예: def read(item_id: int)이면 item_id는 정수여야 합니다.
• /docs는 Swagger UI, /redoc은 ReDoc 문서입니다. 별도 문서 작성 없이 유지됩니다.

자주 만나는 문제

• 실행이 안 되고 ModuleNotFoundError가 뜨면 — 실행에 쓰는 Python과 설치한 환경이 다른 경우가 대부분입니다. 이 문서를 확인하세요.
• --reload는 개발용입니다. 운영 배포 시에는 uvicorn·gunicorn 등 프로세스 관리 방법을 따로 정해야 합니다.

다음 단계

• 공식 튜토리얼의 Request Body, Path Parameters, Dependencies 항목으로 넘어가기
• 데이터베이스 연결은 공식 문서의 SQL(Alchemy) 항목 참고
• 배포는 Docker로 이미지를 만드는 방식이 일반적입니다

검증일은 자료의 최신성을 나타냅니다. 오래된 자료는 적용 조건을 확인하세요.