FastAPI 설치와 시작하기: 첫 API 만들고 문서 확인까지

개발/FastAPI

FastAPI 설치와 시작하기: 첫 API 만들고 문서 확인까지

notebase 2026. 5. 24. 11:33

Python FastAPI 설치부터 가상환경 생성, 첫 API main.py 코드 작성, 서버 실행, 자동 API 문서(docs) 확인까지 초보자 기준으로 직접 따라 할 수 있게 정리한 입문 가이드입니다.

FastAPI 설치를 끝내고 첫 API를 만드는 과정은 생각보다 짧습니다. Python 파일 하나를 만들고, 서버를 실행한 뒤 브라우저에서 응답을 확인하면 기본 흐름은 잡힙니다.

FastAPI는 Python으로 API 서버를 만들 때 자주 쓰이는 웹 프레임워크입니다. Django처럼 큰 웹 서비스 전체를 만들기보다는, 모바일 앱이나 프론트엔드에서 호출할 API 서버를 빠르게 만들 때 많이 사용합니다.

처음 배우는 입장에서는 자동 문서 기능이 특히 편합니다.

코드를 조금만 작성해도 API 문서 화면이 자동으로 만들어집니다. 그래서 내가 만든 API가 제대로 동작하는지 브라우저에서 바로 테스트할 수 있습니다.

FastAPI를 설치하기 전에 필요한 것

먼저 Python이 설치되어 있어야 합니다.

터미널이나 명령 프롬프트에서 아래 명령어를 입력해 봅니다.

python --version

환경에 따라 아래 명령어가 필요할 수 있습니다.

python3 --version

버전이 출력되면 Python은 설치된 상태입니다.

예를 들어 이런 식입니다.

Python 3.12.3

버전이 나오지 않는다면 Python부터 설치해야 합니다. Windows라면 Python 공식 사이트에서 설치할 수 있고, macOS에서는 Homebrew나 공식 설치 파일을 사용할 수 있습니다.

여기서 중요한 점은 FastAPI 자체보다 Python 실행 환경을 먼저 정리하는 것입니다. 설치는 됐는데 python 명령어가 안 먹히면, FastAPI 문제가 아니라 Python 경로 설정 문제일 가능성이 큽니다.

프로젝트 폴더 만들기

먼저 FastAPI 실습용 폴더를 하나 만듭니다.

mkdir fastapi-first-api
cd fastapi-first-api

폴더 이름은 꼭 같을 필요는 없습니다. 다만 처음에는 한글이나 공백이 들어간 폴더명보다 영어 소문자 위주로 만드는 편이 덜 헷갈립니다.

예를 들어 이런 구조로 시작합니다.

fastapi-first-api/

아직 파일은 없습니다.

가상환경 만들기

Python 프로젝트에서는 가상환경을 만들어 두는 편이 좋습니다.

가상환경은 프로젝트마다 패키지를 따로 설치할 수 있게 해주는 공간입니다. 예를 들어 A 프로젝트에서는 FastAPI를 쓰고, B 프로젝트에서는 Django를 쓰더라도 서로 영향을 덜 받습니다.

아래 명령어로 가상환경을 만듭니다.

python -m venv .venv

macOS나 Linux에서 python 명령어가 안 되면 아래처럼 입력합니다.

python3 -m venv .venv

이제 가상환경을 활성화합니다.

Windows PowerShell 기준입니다.

.venv\Scripts\activate.ps1

Windows 명령 프롬프트라면 아래 명령어를 사용합니다.

.venv\Scripts\activate

macOS, Linux에서는 아래처럼 실행합니다.

source .venv/bin/activate

활성화되면 터미널 앞쪽에 (.venv) 같은 표시가 붙습니다.

(.venv) fastapi-first-api %

이 표시가 보이면 현재 프로젝트 안의 가상환경을 사용 중이라는 뜻입니다.

FastAPI 설치하기

이제 FastAPI를 설치합니다.

2026년 5월 기준 FastAPI 공식 문서는 아래 명령어를 안내하고 있습니다.

pip install "fastapi[standard]"

예전 글에서는 아래처럼 설치하는 방식을 자주 볼 수 있습니다.

pip install fastapi uvicorn

이 방식이 아예 틀린 것은 아닙니다. 다만 처음 시작하는 입장에서는 공식 문서 흐름대로 fastapi[standard]를 설치하는 편이 덜 헷갈립니다.

fastapi[standard]로 설치하면 FastAPI를 실행하고 개발하는 데 필요한 표준 의존성이 함께 설치됩니다. 그래서 이 글에서도 이 방식을 기준으로 진행합니다.

설치가 끝났는지 확인하려면 아래 명령어를 입력합니다.

fastapi --version

버전 정보가 출력되면 설치가 된 것입니다.

첫 API 파일 만들기

이제 main.py 파일을 만듭니다.

프로젝트 폴더 안이 아래와 같은 구조가 되도록 파일을 생성해 주세요.

fastapi-first-api/
├── .venv/
└── main.py

main.py 파일에 아래 코드를 작성하고 저장합니다.

# main.py
from fastapi import FastAPI

app = FastAPI()


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

코드는 짧지만 FastAPI의 기본 구조가 들어 있습니다.

코드에서 봐야 할 부분은 세 가지입니다. - from fastapi import FastAPI: FastAPI 클래스를 가져옵니다. - app = FastAPI(): API 서버 역할을 할 앱 객체를 만듭니다. - @app.get("/"): / 주소로 들어온 GET 요청을 아래 함수와 연결합니다.

마지막 함수는 실제 응답을 반환합니다.

def read_root():
    return {"message": "Hello FastAPI"}

여기서는 Python 딕셔너리를 반환했지만, 브라우저에서는 JSON 형태로 응답이 보입니다.

FastAPI 서버 실행하기

이제 서버를 실행합니다.

터미널에서 main.py가 있는 폴더 위치인지 확인한 뒤 아래 명령어를 입력합니다.

fastapi dev main.py

정상적으로 실행되면 터미널에 서버 주소가 표시됩니다.

보통 아래 주소를 사용합니다.

http://127.0.0.1:8000

브라우저 주소창에 아래 주소를 입력합니다.

http://127.0.0.1:8000

화면에 아래와 비슷한 응답이 나오면 성공입니다.

{
  "message": "Hello FastAPI"
}

이게 첫 번째 API입니다.

아직 데이터베이스도 없고, 로그인도 없고, 복잡한 구조도 없습니다. 하지만 브라우저가 API 서버에 요청을 보내고, FastAPI가 JSON 응답을 돌려주는 흐름은 이미 만들어졌습니다.

자동 API 문서 확인하기

FastAPI의 장점 중 하나는 API 문서를 자동으로 만들어준다는 점입니다.

서버가 실행 중인 상태에서 아래 주소로 접속해 봅니다.

http://127.0.0.1:8000/docs

그러면 Swagger UI 화면이 열립니다.

여기서 / API를 직접 실행해볼 수 있습니다.

**GET /** 항목을 클릭합니다.
**Try it out** 버튼을 누릅니다.
**Execute** 버튼을 누릅니다.
하단의 Response body에서 응답 결과를 확인합니다.

코드로 만든 API를 브라우저 문서 화면에서 바로 테스트할 수 있는 구조입니다.

ReDoc 문서도 기본으로 제공됩니다.

http://127.0.0.1:8000/redoc

/docs는 테스트하기 좋고, /redoc은 문서처럼 읽기 좋습니다. 처음 배울 때는 /docs를 더 자주 보게 됩니다.

경로를 하나 더 추가해보기

이번에는 API를 하나 더 만들어보겠습니다.

main.py를 아래처럼 수정합니다.

# main.py
from fastapi import FastAPI

app = FastAPI()


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


@app.get("/items")
def read_items():
    return {
        "items": [
            {"id": 1, "name": "keyboard"},
            {"id": 2, "name": "mouse"},
        ]
    }

서버가 실행 중이라면 저장 후 다시 확인합니다.

http://127.0.0.1:8000/items

아래처럼 응답이 나옵니다.

{
  "items": [
    {
      "id": 1,
      "name": "keyboard"
    },
    {
      "id": 2,
      "name": "mouse"
    }
  ]
}

그리고 /docs에 다시 들어가면 GET /items API가 자동으로 추가되어 있습니다.

여기서 중요한 점은 문서를 따로 작성하지 않았다는 것입니다. FastAPI가 코드 구조를 보고 API 문서를 만들어줍니다.

쿼리 파라미터 받아보기

API는 보통 클라이언트에서 값을 받아 처리합니다.

이번에는 name 값을 받아서 응답하는 API를 만들어보겠습니다.

main.py를 아래처럼 수정합니다.

# main.py
from fastapi import FastAPI

app = FastAPI()


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


@app.get("/items")
def read_items():
    return {
        "items": [
            {"id": 1, "name": "keyboard"},
            {"id": 2, "name": "mouse"},
        ]
    }


@app.get("/hello")
def say_hello(name: str = "FastAPI"):
    return {"message": f"Hello, {name}"}

브라우저에서 아래 주소로 접속합니다.

http://127.0.0.1:8000/hello

응답은 이렇게 나옵니다.

{
  "message": "Hello, FastAPI"
}

이번에는 주소 뒤에 name 값을 붙여봅니다.

http://127.0.0.1:8000/hello?name=Python

그러면 응답이 바뀝니다.

{
  "message": "Hello, Python"
}

name: str = "FastAPI" 부분이 핵심입니다.

def say_hello(name: str = "FastAPI"):

FastAPI는 함수 인자를 보고 쿼리 파라미터로 처리합니다. name 값이 들어오면 그 값을 사용하고, 없으면 기본값인 "FastAPI"를 사용합니다.

이 부분이 FastAPI를 처음 배울 때 꽤 중요한 감각입니다.

API 주소, 함수 인자, 응답 데이터가 어떻게 연결되는지 이해하면 이후 경로 파라미터, 요청 본문, 데이터 검증도 훨씬 쉽게 이어집니다.

서버와 가상환경 종료하기

개발 서버를 끄려면 터미널에서 아래 키를 누릅니다.

Ctrl + C

서버가 종료되면 브라우저에서 접속해도 응답이 나오지 않습니다.

다시 실행하려면 같은 명령어를 입력하면 됩니다.

fastapi dev main.py

서버를 종료한 뒤 가상환경에서도 빠져나가고 싶다면 아래 명령어를 입력합니다.

deactivate

다시 FastAPI 작업을 하려면 가상환경을 다시 활성화한 뒤 서버를 실행하면 됩니다.

자주 막히는 부분

`fastapi` 명령어를 찾을 수 없다고 나오는 경우

가상환경이 활성화되어 있는지 먼저 확인합니다.

터미널 앞에 (.venv) 표시가 없다면 다시 활성화합니다.

Windows PowerShell:

.venv\Scripts\activate.ps1

macOS, Linux:

source .venv/bin/activate

그래도 안 된다면 FastAPI가 현재 가상환경에 설치되지 않았을 수 있습니다.

pip install "fastapi[standard]"

`python` 명령어가 안 되는 경우

macOS나 Linux에서는 python3를 사용해야 할 수 있습니다.

python3 -m venv .venv

Windows에서는 Python 설치 시 Add python.exe to PATH 옵션이 빠졌을 가능성이 있습니다. 이 경우 Python을 다시 설치하거나 환경 변수를 확인해야 합니다.

브라우저에서 접속이 안 되는 경우

서버가 실행 중인지 확인합니다.

터미널에 서버 실행 로그가 떠 있어야 합니다. 서버를 실행한 터미널을 닫았거나 Ctrl + C로 종료했다면 다시 실행해야 합니다.

fastapi dev main.py

또 주소를 정확히 입력했는지도 확인합니다.

http://127.0.0.1:8000

https가 아니라 http입니다.

8000번 포트가 이미 사용 중이라고 나오는 경우

fastapi dev main.py를 실행했을 때 8000번 포트가 이미 사용 중이라는 에러가 나올 수 있습니다.

이전에 실행한 FastAPI 서버가 아직 종료되지 않았거나, 다른 프로그램이 같은 포트를 사용 중일 때 생깁니다.

먼저 기존 서버가 실행 중인 터미널에서 Ctrl + C를 눌러 종료해 봅니다.

그래도 문제가 계속되면 다른 포트로 실행할 수 있습니다.

fastapi dev main.py --port 8001

이 경우 브라우저에서는 아래 주소로 접속합니다.

http://127.0.0.1:8001

포트 번호만 바뀌었을 뿐, API 코드가 달라지는 것은 아닙니다.

처음에는 여기까지만 해도 충분하다

FastAPI를 처음 배울 때 바로 데이터베이스, 로그인, 배포까지 가면 구조가 복잡해집니다.

먼저 아래 흐름을 확실히 잡는 게 좋습니다.

가상환경 생성
→ FastAPI 설치
→ main.py 작성
→ fastapi dev main.py 실행
→ 브라우저에서 API 응답 확인
→ /docs에서 테스트

FastAPI는 처음 진입 장벽이 낮은 편이지만, 실제 백엔드 개발로 가면 구조 설계가 중요해집니다. 그래서 처음에는 많은 기능을 한 번에 외우기보다, API 하나가 요청을 받고 응답을 돌려주는 흐름부터 손에 익히는 편이 낫습니다.

'개발 > FastAPI' 카테고리의 다른 글

FastAPI Swagger 문서 자동 생성, `/docs` 화면이 만들어지는 원리 (0)	2026.05.26
FastAPI Pydantic 모델 기초: 요청 데이터를 검증하는 방법 (0)	2026.05.26
FastAPI Path Parameter와 Query Parameter 차이 정리 (0)	2026.05.24
FastAPI GET, POST 요청 이해하기: 조회와 데이터 전송의 차이 (0)	2026.05.24
FastAPI란? Flask·Django 차이와 파이썬 백엔드 선택 기준 (0)	2026.05.23

현재글FastAPI 설치와 시작하기: 첫 API 만들고 문서 확인까지

Notebase