Serializer와 응답 예시를 명확하게 문서화하는 팁

Django DRF에서 drf-spectacular 사용 시 API 문서를 더 명확하고 실용적으로 만드는 방법. 자동 생성된 문서의 한계를 극복하고 개발자 경험을 향상시키는 구체적인 기법들을 다룸

help_text로 필드 설명 추가

• Serializer 필드에 help_text 추가하여 Swagger UI에서 Description으로 표시

• 필드의 역할, 포맷, 제약 조건을 명확하게 설명

• 특히 ChoiceField의 경우 각 choice 의미를 help_text에 명시

class UserProfileSerializer(serializers.ModelSerializer):
    nickname = serializers.CharField(
        max_length=50,
        help_text="사용자가 앱 내에서 사용할 별명 (중복 불가)"
    )
    status = serializers.ChoiceField(
        choices=UserStatus.choices,
        help_text="사용자 상태 (ACTIVE: 활성, DORMANT: 휴면, WITHDRAWN: 탈퇴)"
    )

@extend_schema_field로 SerializerMethodField 타입 명시

• SerializerMethodField는 기본적으로 string 타입으로 표시되는 문제 해결

• @extend_schema_field 데코레이터로 정확한 타입 지정

• OpenApiTypes의 다양한 기본 타입 활용 (INT, BOOL, DATE, DATETIME, UUID 등)

from drf_spectacular.utils import extend_schema_field
from drf_spectacular.types import OpenApiTypes

class PostSerializer(serializers.ModelSerializer):
    @extend_schema_field(OpenApiTypes.INT)
    def get_comments_count(self, obj):
        return obj.comments.count()

@extend_schema로 응답 스키마 직접 정의

• 모델 Serializer와 다른 커스텀 구조 응답 시 @extend_schema의 responses 인자 활용

• 문서화 전용 응답 Serializer 생성으로 실제 응답과 정확히 일치하는 스키마 제공

• 페이징 정보나 메타 데이터 포함 응답 구조 명확히 문서화

# 문서화 전용 응답 Serializer
class PostListResponseSerializer(serializers.Serializer):
    count = serializers.IntegerField(help_text="전체 게시글 수")
    next = serializers.URLField(allow_null=True, help_text="다음 페이지 URL")
    results = PostSerializer(many=True)

@extend_schema(responses={200: PostListResponseSerializer})
def get(self, request, *args, **kwargs):
    return super().get(request, *args, **kwargs)

@extend_schema로 구체적인 예시 제공

• OpenApiExample 객체를 사용하여 Request/Response 예시를 Swagger UI에 추가

• 예시에 이름과 설명을 붙여 가독성 향상

• request_only, response_only, status_codes 옵션으로 적절한 위치에 예시 표시

@extend_schema(
    examples=[
        OpenApiExample(
            '성공적인 생성 예시',
            value={"username": "testuser", "email": "[email protected]"},
            request_only=True
        ),
        OpenApiExample(
            '성공 응답',
            value={"id": 123, "username": "testuser"},
            response_only=True
        )
    ]
)