계층 구조 태그 지원 없이 FastAPI에서의 대체 방법

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

웹 개발

대상자

• FastAPI를 사용하는 백엔드 개발자
• OpenAPI 문서화 필요성 있는 프로젝트 팀
• API 구조를 시각적으로 명확히 표현하고자 하는 개발자
• 난이도: 중간 (간단한 코드 수정과 높은 유지보수성 요구)

핵심 요약

• FastAPI/OpenAPI 3.1.0은 계층 구조 태그를 지원하지 않음
• 계층 구조를 시뮬레이션하기 위해 · 기호로 태그 이름을 분리 (예: Customers · Business)
• Enum 사용으로 태그 이름 중앙 관리 가능 (예: Tags.customers_individual)

섹션별 세부 요약

1. 문제 상황

• OpenAPI 3.1.0에서 태그는 플랫 리스트만 지원
• 계층 구조 태그 지원 예정: OpenAPI 3.2.0 (2025년 8월 예상)
• FastAPI 및 Swagger UI/Redoc은 3.2.0 지원 후 업데이트 필요

2. 대체 방안 (Workaround)

• 태그 이름에 계층 정보 포함 (예: Customers · Business · Domestic)
• Swagger UI에서 긴 태그 이름 전체 표시 가능
• Redoc에서 태그 이름 줄 바꿈 방지 필요

3. 구현 방법

• Enum 클래스로 태그 정의 (중심 관리)

from enum import Enum
class Tags(str, Enum):
    customers_individual = "Customers · Individual"

• tags_metadata에 Enum 값 사용

tags_metadata = [{"name": tag.value} for tag in Tags]

• 라우트에 태그 적용

@app.get("/v1/customer/b2c", tags=[Tags.customers_individual])

4. 장단점

• 장점
• Swagger UI에서 계층 구조 시각적 표현 가능
• OpenAPI 3.1.0 호환성 보장
• 단점
• Redoc에서 태그 이름 길이 제한 필요
• 계층 구조는 외관적 해결책이며 실제 중첩 구조 지원 X

5. Swagger UI 최적화 팁

• 기본적으로 모든 엔드포인트 전개 상태로 표시
• 팀원이 API 구조를 쉽게 이해하도록 그룹별 접기 권장

결론

• OpenAPI 3.2.0 지원 전에는 Enum 기반 태그 중앙 관리가 유지보수성 향상에 유리
• Redoc 사용 시 태그 이름 길이 제한 (예: 30자 이내)으로 줄 바꿈 방지
• Swagger UI에서 계층 구조 시각적 표현 가능하나, 실제 중첩 구조는 OpenAPI 3.2.0 이후 필요