Router Tags 활용

FastAPI의 include_router에서 사용되는 tags는 OpenAPI(Swagger) 문서화와 API 그룹화에 매우 유용합니다. 특히 Enum을 활용하면 일관성 있는 태그 관리가 가능합니다.

기본적인 태그 사용법

가장 단순한 형태의 태그 사용입니다.

from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter()

# 문자열 리스트로 태그 지정
app.include_router(
    router,
    prefix="/users",
    tags=["users", "auth"]  # 여러 태그 지정 가능
)

Enum을 활용한 태그 관리

대규모 애플리케이션에서는 Enum을 사용하여 태그를 체계적으로 관리할 수 있습니다.

from enum import Enum
from fastapi import APIRouter, FastAPI

class Tags(str, Enum):
    USERS = "users"
    ADMIN = "admin"
    ITEMS = "items"
    AUTHENTICATION = "authentication"
    MONITORING = "monitoring"

app = FastAPI()

# 사용자 관련 라우터
user_router = APIRouter()
app.include_router(
    user_router,
    prefix="/users",
    tags=[Tags.USERS, Tags.AUTHENTICATION]
)

# 관리자 관련 라우터
admin_router = APIRouter()
app.include_router(
    admin_router,
    prefix="/admin",
    tags=[Tags.ADMIN, Tags.MONITORING]
)

태그별 문서화 설정

각 태그에 대한 상세 설명을 추가할 수 있습니다.

from fastapi import FastAPI
from enum import Enum

class Tags(str, Enum):
    USERS = "users"
    ITEMS = "items"

app = FastAPI(
    title="My API",
    openapi_tags=[
        {
            "name": Tags.USERS,
            "description": "사용자 관리 관련 작업",
            "externalDocs": {
                "description": "사용자 관리 문서",
                "url": "https://example.com/docs/users",
            },
        },
        {
            "name": Tags.ITEMS,
            "description": "상품 관리 관련 작업",
        },
    ]
)

태그를 활용한 권한 관리

태그를 기반으로 API 접근 권한을 관리할 수 있습니다.

from enum import Enum
from fastapi import Depends, HTTPException, Security
from fastapi.security import OAuth2PasswordBearer

class UserRole(str, Enum):
    ADMIN = "admin"
    USER = "user"

class Tags(str, Enum):
    ADMIN = "admin"
    USER = "user"

def check_tag_permission(required_role: UserRole):
    async def permissions_dependency(
        user_role: UserRole = Depends(get_user_role)
    ):
        if user_role != required_role:
            raise HTTPException(
                status_code=403,
                detail="Permission denied"
            )
    return permissions_dependency

admin_router = APIRouter(dependencies=[Depends(check_tag_permission(UserRole.ADMIN))])
app.include_router(
    admin_router,
    prefix="/admin",
    tags=[Tags.ADMIN]
)

이처럼 include_router의 tags 매개변수는 단순한 문서화 도구를 넘어서, 애플리케이션의 구조화와 권한 관리에도 활용할 수 있습니다.