[FastAPI] add_api_route 파라미터

FastAPI의 add_api_route는 매우 강력한 기능을 제공하지만, 많은 매개변수로 인해 처음에는 이해하기 어려울 수 있습니다. 각 매개변수의 역할과 실제 활용 방법에 대해 알아보겠습니다.

필수 매개변수 이해하기

from fastapi import FastAPI, Response
from typing import List, Dict, Any

app = FastAPI()

# 기본적인 매개변수 사용
app.add_api_route(
    path="/users",              # 엔드포인트 경로
    endpoint=get_users,         # 실행될 함수
    methods=["GET"]             # HTTP 메서드
)

응답 관련 매개변수

응답 형식과 관련된 매개변수들은 API의 출력을 제어합니다.

from pydantic import BaseModel

class UserResponse(BaseModel):
    id: int
    name: str
    email: str

app.add_api_route(
    path="/users/{user_id}",
    endpoint=get_user,
    response_model=UserResponse,           # 응답 데이터 모델
    status_code=200,                       # HTTP 상태 코드
    response_description="User found",     # 응답 설명
    response_model_exclude={"password"},   # 제외할 필드
    response_model_by_alias=True,         # 별칭 사용 여부
    responses={                           # 가능한 응답 정의
        404: {"description": "User not found"},
        400: {"description": "Invalid ID"}
    }
)

문서화 관련 매개변수

API 문서 자동 생성을 위한 매개변수들입니다.

app.add_api_route(
    path="/users",
    endpoint=create_user,
    tags=["users"],                    # API 그룹화
    summary="Create new user",         # API 요약
    description="Creates a new user in the system", # 상세 설명
    deprecated=False,                  # 사용 중단 여부
    operation_id="createUser",         # 작업 고유 ID
    include_in_schema=True            # 스키마 포함 여부
)

대규모 API 관리를 위한 구조화

API가 많아질 때는 다음과 같은 구조로 관리하면 효과적입니다:

# api/routes/base.py
from typing import Type
from fastapi import APIRouter

class BaseRouter:
    def __init__(self, prefix: str, tags: List[str]):
        self.router = APIRouter(prefix=prefix, tags=tags)

    def configure(self) -> APIRouter:
        self._register_routes()
        return self.router

    def _register_routes(self):
        raise NotImplementedError

# api/routes/users.py
class UserRouter(BaseRouter):
    def __init__(self):
        super().__init__(prefix="/users", tags=["users"])

    def _register_routes(self):
        self.router.add_api_route(
            path="",
            endpoint=self.get_users,
            methods=["GET"],
            response_model=List[UserResponse],
            summary="Get all users",
            description="Retrieves a list of all users"
        )

        self.router.add_api_route(
            path="/{user_id}",
            endpoint=self.get_user,
            methods=["GET"],
            response_model=UserResponse,
            summary="Get user by ID"
        )

    async def get_users(self):
        return await UserService.get_all()

    async def get_user(self, user_id: int):
        return await UserService.get_by_id(user_id)

# main.py
app = FastAPI()

def configure_routes(app: FastAPI):
    routers = [
        UserRouter(),
        ProductRouter(),
        OrderRouter()
    ]

    for router in routers:
        app.include_router(router.configure())

configure_routes(app)

고급 기능 활용

from fastapi import Depends, Security
from typing import Callable

class APIRouteManager:
    def __init__(self, app: FastAPI):
        self.app = app
        self.common_responses = {
            401: {"description": "Unauthorized"},
            403: {"description": "Forbidden"},
            500: {"description": "Internal Server Error"}
        }

    def add_secured_route(
        self,
        path: str,
        endpoint: Callable,
        auth_handler: Callable,
        **kwargs
    ):
        # 기본 응답 합치기
        responses = {
            **self.common_responses,
            **(kwargs.get("responses", {}))
        }

        # 의존성 추가
        dependencies = [
            Depends(auth_handler),
            *(kwargs.get("dependencies", []))
        ]

        self.app.add_api_route(
            path=path,
            endpoint=endpoint,
            dependencies=dependencies,
            responses=responses,
            **kwargs
        )

# 사용 예시
route_manager = APIRouteManager(app)
route_manager.add_secured_route(
    path="/admin/users",
    endpoint=admin_get_users,
    auth_handler=check_admin_token,
    methods=["GET"],
    summary="Admin: Get all users"
)

매개변수 설정 가이드라인

1. 필수 설정
   • path: API 엔드포인트 경로
   • endpoint: 실행될 함수
   • methods: HTTP 메서드
2. 권장 설정
   • response_model: 응답 데이터 구조 정의
   • status_code: 기본 HTTP 상태 코드
   • tags: API 그룹화
   • summary: API 간단 설명
   • responses: 가능한 응답 정의
3. 선택적 설정
   • dependencies: 의존성 주입
   • deprecated: API 사용 중단 표시
   • operation_id: API 작업 식별자
   • response_model_exclude: 제외할 필드

이러한 구조화된 접근 방식을 통해 대규모 API도 효과적으로 관리할 수 있으며, 코드의 재사용성과 유지보수성을 높일 수 있습니다.