들어가며
FastAPI를 사용하여 API를 개발할 때 가장 기본이 되는 개념이 바로 Path Parameter와 Query Parameter입니다. 이 두 가지 매개변수는 클라이언트로부터 데이터를 받는 핵심 방법이며, RESTful API 설계의 기초가 됩니다.
오늘은 이 두 매개변수를 어떻게 정의하고, 유효성 검증을 추가하며, FastAPI의 자동 문서화 기능과 어떻게 통합되는지 자세히 알아보겠습니다.
1. API 자동 문서화 - Swagger UI와 ReDoc
FastAPI의 가장 큰 장점 중 하나는 자동 문서화 기능입니다. 코드를 작성하면 별도의 작업 없이 API 문서가 자동으로 생성됩니다.
Swagger UI 접근하기
FastAPI 서버를 실행한 후 브라우저에서 http://127.0.0.1:8000/docs에 접속하면 Swagger UI를 볼 수 있습니다.
Swagger UI의 주요 기능:
- 모든 API 엔드포인트 확인
- 요청/응답 형식 자동 표시
- Try it out 버튼으로 직접 API 테스트 가능
- OpenAPI Specification 기반
ReDoc 문서
http://127.0.0.1:8000/redoc에 접속하면 ReDoc UI를 사용할 수 있습니다. ReDoc은 Swagger UI보다 더 깔끔한 문서 형식을 제공하며, API 스펙을 읽기 좋은 형태로 보여줍니다.
2. Path Parameters - URL 경로에서 데이터 받기
Path Parameter는 URL 경로의 일부로 전달되는 매개변수입니다. 주로 특정 리소스를 식별할 때 사용됩니다.
기본 사용법
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def get_item(item_id):
return {"item_id": item_id}/items/100으로 요청하면item_id에"100"이 전달됩니다.- 중괄호
{}로 Path Parameter를 정의합니다.
타입 지정과 자동 검증
@app.get("/items/{item_id}")
def get_item(item_id: int):
return {"item_id": item_id}item_id를int로 지정하면 FastAPI가 자동으로 타입을 변환합니다.- 잘못된 타입이 입력되면 422 Unprocessable Entity 오류를 반환합니다.
- 예:
/items/abc로 요청하면 422 오류 발생
경로 순서의 중요성
FastAPI는 경로를 선언된 순서대로 매칭합니다.
@app.get("/items/search")
def search_items():
return {"message": "search"}
@app.get("/items/{item_id}")
def get_item(item_id: str):
return {"item_id": item_id}⚠️ /items/search를 먼저 선언해야 합니다. 그렇지 않으면 search가 item_id로 인식됩니다.
Path() 함수로 고급 검증
from fastapi import FastAPI, Path
@app.get("/items/{item_id}")
def read_item(item_id: int = Path(..., ge=1)):
return {"item_id": item_id}...(Ellipsis): 필수 매개변수ge=1: Greater than or Equal, 1 이상의 값만 허용- 다른 검증 옵션:
gt(초과),le(이하),lt(미만)
문자열 검증
@app.get("/items/{item_name}")
def get_item_by_name(item_name: str = Path(..., max_length=6)):
return {"item_name": item_name}max_length=6: 최대 6자까지만 허용- 7자 이상 입력 시
string_too_long오류 발생
3. Query Parameters - URL 쿼리 문자열로 데이터 받기
Query Parameter는 URL 끝에 ?key=value 형태로 전달되는 매개변수입니다. 필터링, 정렬, 페이지네이션 등에 주로 사용됩니다.
기본 사용법
@app.get("/search")
def search_items(q: str):
return {"searched": q}/search?q=python으로 요청하면q에"python"이 전달됩니다.- Path Parameter에 포함되지 않은 함수 매개변수는 자동으로 Query Parameter가 됩니다.
기본값 설정
@app.get("/search")
def search_items(q: str = "default_value"):
return {"searched": q}/search로 요청 시q는"default_value"가 됩니다./search?q=myquery로 요청하면q는"myquery"가 됩니다.
선택적 매개변수
@app.get("/items")
def read_items(skip: int = 0, limit: int = 10):
return {"skip": skip, "limit": limit}/items:skip=0,limit=10(기본값)/items?skip=5&limit=20:skip=5,limit=20
Query() 함수로 고급 검증
from fastapi import FastAPI, Query
@app.get("/search")
def search_items(
q: str = Query(default="default", min_length=2, max_length=8)
):
return {"searched": q}min_length=2: 최소 2자 이상max_length=8: 최대 8자 이하- 조건을 만족하지 않으면 422 오류 발생
필수 Query Parameter
@app.get("/search")
def search_items(q: str = Query(...)):
return {"searched": q}...(Ellipsis)를 사용하면 필수 매개변수가 됩니다.- 쿼리 없이 요청하면 422 오류 발생
4. Path와 Query를 함께 사용하기
실제 API에서는 Path Parameter와 Query Parameter를 함께 사용하는 경우가 많습니다.
from fastapi import FastAPI, Path, Query
app = FastAPI()
@app.get("/users/{user_id}/items/{item_id}")
def read_user_item(
user_id: int = Path(..., title="User ID"),
item_id: str = Path(..., title="Item ID"),
q: str = None,
short: bool = False
):
item = {"item_id": item_id, "owner_id": user_id}
if q:
item.update({"q": q})
if not short:
item.update(
{"description": "This is an amazing item that has a long description"}
)
return item사용 예시:
/users/1/items/item_1: 기본 정보만 반환/users/1/items/item_1?q=test&short=true: 검색어 포함, 짧은 설명
5. FastAPI 실행 팁
개발 모드로 실행하기
fastapi dev main.py다른 파일에서 app 객체 불러오기
fastapi dev -e pathparam.py:app-e또는--entrypoint옵션 사용파일명:app객체명형식으로 지정
⚠️ Address already in use 오류가 발생하면 Ctrl+C로 기존 서버를 종료하세요.
마무리
오늘 배운 내용을 정리하면:
✅ Path Parameter: URL 경로의 일부로 데이터 전달 (/items/{item_id})
✅ Query Parameter: URL 쿼리 문자열로 데이터 전달 (/items?skip=0&limit=10)
✅ Path()와 Query(): 고급 검증 기능 제공
✅ 자동 문서화: Swagger UI와 ReDoc으로 API 문서 자동 생성
✅ 타입 지정: FastAPI가 자동으로 타입 변환 및 검증 수행
Path와 Query Parameter는 FastAPI의 가장 기본적인 개념이지만, 이를 제대로 이해하면 강력하고 안전한 API를 만들 수 있습니다. 다음 시간에는 Request Body와 Pydantic 모델을 활용한 데이터 검증에 대해 알아보겠습니다!
참고 자료:
