@extend_schema를 활용해 자동화가 어려운 API까지 완벽하게 문서화

drf-spectacular의 @extend_schema 데코레이터를 사용하여 자동 추론이 불가능한 복잡한 API들을 완벽하게 문서화하는 방법

@extend_schema가 필요한 상황

• 비정형 데이터 처리: request.data를 직접 파싱하는 APIView

• 파일 업로드/다운로드: MultiPartParser 사용 시 스키마가 불분명한 경우

• 동적 응답 구조: 요청 파라미터나 사용자 상태에 따라 응답 필드가 변경

• 다중 상태 코드: 다양한 성공/에러 케이스 명시

• 복잡한 쿼리 파라미터: django-filter 미사용 시 커스텀 필터 파라미터 설명

핵심 파라미터 활용법

1. request: 요청 본문 명세화

@extend_schema(
    request=UserGreetingSerializer,  # Serializer 참조 권장
    summary="이름으로 인사하기",
    tags=["Greetings"]
)
def post(self, request):
    return Response(...)

2. responses: 다양한 응답 케이스 명세화

@extend_schema(
    responses={
        201: ArticleSerializer,
        400: ErrorResponseSerializer,
        401: ErrorResponseSerializer,
        404: {"description": "해당 ID의 게시글을 찾을 수 없음"}
    }
)

3. parameters: 쿼리/경로 파라미터 명세화

@extend_schema(
    parameters=[
        OpenApiParameter(
            name='search',
            type=OpenApiTypes.STR,
            location=OpenApiParameter.QUERY,
            description='검색할 상품명',
            required=False
        )
    ]
)

4. examples: 구체적인 예시 추가

@extend_schema(
    examples=[
        OpenApiExample(
            '성공적인 로그인 예시',
            value={"username": "testuser", "password": "password123!"},
            request_only=True
        )
    ]
)

실무 활용 팁

• Serializer 우선: 딕셔너리보다 Serializer 참조로 코드 재사용성 확보

• 공통 응답 재사용: 401, 403 등 공통 에러 응답은 데코레이터나 헬퍼 함수로 관리

• django-filter 중복 방지: filterset_class 사용 시 자동 생성되므로 중복 정의 금지

• @extend_schema_view: 클래스 전체에 공통 설정 적용 시 사용