[새싹 성동 2기] FastAPI 경로 매개변수와 Path 클래스를 활용한 유효성 검사

FastAPI는 경로 매개변수(Path Parameter)를 통해 URL의 특정 값을 받아 서버에서 처리할 수 있도록 지원합니다. 이 기능은 RESTful API 개발에서 자주 사용되며, 클라이언트가 서버로 특정 리소스를 요청할 때 매우 유용합니다. 이번 글에서는 FastAPI에서 경로 매개변수를 사용하는 방법과 이를 Path 클래스를 활용해 유효성 검사 및 메타데이터를 추가하는 방법을 소개합니다.

1. 경로 매개변수란?

경로 매개변수는 URL 경로의 일부로 전달되는 값으로, FastAPI에서 중괄호 {}로 표시됩니다. 클라이언트가 URL을 통해 특정 리소스를 요청하면 서버는 이 값을 사용해 작업을 수행합니다.

예시:

• 경로: /users/{user_id}
• 요청: /users/100
• 결과: 서버는 user_id=100 값을 처리.

2. 간단한 예제: 할 일 상세 조회 API

다음은 FastAPI로 간단한 할 일(Todo) 관리 API를 구현한 예제입니다. 여기서는 경로 매개변수를 활용해 특정 ID와 일치하는 할 일을 반환합니다.

todo.py

from fastapi import APIRouter
from model import Todo

todo_router = APIRouter()

# 임시 저장소
todo_list = []

@todo_router.post("/todo")
def add_todo(todo: Todo) -> dict:
    todo_list.append(todo)
    return {"message": "할 일을 추가합니다."}

@todo_router.get("/todo")
def retrives_todo() -> dict:
    return {"todos": todo_list}

# 할 일 상세 조회
@todo_router.get("/todo/{todo_id}")
def retrive_todo(todo_id: int) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            return {"todo": todo}

    return {"message": "일치하는 할 일이 없습니다."}

테스트

1. 할 일 추가

   curl http://localhost:8000/todo -X POST -d "{ \"id\": 1, \"item\": \"첫번째 할 일\"}" -H "Content-Type: application/json"
   curl http://localhost:8000/todo -X POST -d "{ \"id\": 2, \"item\": \"두번째 할 일\"}" -H "Content-Type: application/json"

   
   
   
2. 할 일 목록 조회

   curl http://localhost:8000/todo

   
   
   
   
3. 할 일 상세 조회

   curl http://localhost:8000/todo/1
   curl http://localhost:8000/todo/2
   curl http://localhost:8000/todo/100  # 존재하지 않는 ID 요청

   
   

결과

• 성공: { "todo": { "id": 1, "item": "첫번째 할 일" }}
• 실패: { "message": "일치하는 할 일이 없습니다." }

3. Path 클래스를 활용한 유효성 검사 및 메타데이터 추가

Path 클래스는 경로 매개변수에 대해 다음과 같은 기능을 제공합니다:

• 기본값 설정
• 유효성 검사(값 범위 제한)
• 설명 추가

수정된 코드

다음은 Path 클래스를 사용해 todo_id 매개변수에 유효성 검사 및 메타데이터를 추가한 코드입니다.

 

from fastapi import APIRouter, Path
from model import Todo

todo_router = APIRouter()

todo_list = []

@todo_router.post("/todo")
def add_todo(todo: Todo) -> dict:
    todo_list.append(todo)
    return {"message": "할 일을 추가합니다."}

@todo_router.get("/todo")
def retrives_todo() -> dict:
    return {"todos": todo_list}

# 할 일 상세 조회
@todo_router.get("/todo/{todo_id}")
def retrive_todo(todo_id: int = Path(..., title="조회할 할 일의 ID", ge=1)) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            return {"todo": todo}

    return {"message": "일치하는 할 일이 없습니다."}

 

주요 변경점

1. Path 클래스 사용
   • ...: 필수 매개변수로 지정
   • title: 매개변수 설명 추가
   • ge=1: 매개변수가 1 이상의 값만 허용되도록 유효성 검사 추가
2. 유효성 검사 메시지
   • 잘못된 ID 요청 시, 상세한 에러 메시지가 자동 생성됨.

테스트

curl http://localhost:8000/todo/0

 

결과:

 

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["path", "todo_id"],
      "msg": "Input should be greater than or equal to 1",
      "input": "0",
      "ctx": {"ge": 1}
    }
  ]
}

 

 

4. 자동 문서화

FastAPI는 OpenAPI를 기반으로 API 문서를 자동 생성합니다. Path 클래스로 추가한 메타데이터도 문서화에 반영됩니다.

Swagger UI: http://localhost:8000/docs

ReDoc: http://localhost:8000/redoc

 

FastAPI의 경로 매개변수와 Path 클래스는 RESTful API 개발에서 매우 유용하며, 강력한 유효성 검사와 문서화 기능을 제공합니다. 위 코드를 참고해 여러분의 프로젝트에서도 효율적이고 안전한 API를 개발해 보세요!

 

참고 자료

• FastAPI 공식 문서: 경로 매개변수

 

*생성형 AI 활용한 클라우드&보안 전문가 양성캠프 과정의 교육내용 정리 자료입니다.