Enum과 TypedDict를 활용해 문서 가독성 높이기

API 문서의 가독성을 높이기 위해 Python의 Enum과 TypedDict를 활용하여 매직 스트링을 제거하고 복잡한 딕셔너리 구조를 명확하게 정의하는 방법

Enum으로 매직 스트링 제거

매직 스트링 문제점

• 오타 발생 가능성

• 의미 파악의 어려움

• 유지보수의 어려움

Django 모델에 Enum 적용

from django.db import models

class Order(models.Model):
    class OrderStatus(models.TextChoices):
        PENDING = "PENDING", "주문 대기"
        PAID = "PAID", "결제 완료"
        SHIPPING = "SHIPPING", "배송 중"
        COMPLETED = "COMPLETED", "배송 완료"
        CANCELED = "CANCELED", "주문 취소"

    status = models.CharField(
        max_length=10,
        choices=OrderStatus.choices,
        default=OrderStatus.PENDING
    )

TypedDict로 복잡한 Dict 구조 명확화

문제 상황: SerializerMethodField가 반환하는 dict 구조를 알 수 없음

해결 방법: TypedDict와 @extend_schema_field 활용

from typing import TypedDict
from drf_spectacular.utils import extend_schema_field

class ActivitySummaryDict(TypedDict):
    last_login_at: str
    post_count: int
    comment_count: int

class UserStatsSerializer(serializers.ModelSerializer):
    activity_summary = serializers.SerializerMethodField()

    @extend_schema_field(ActivitySummaryDict)
    def get_activity_summary(self, obj) -> ActivitySummaryDict:
        return {
            "last_login_at": obj.last_login,
            "post_count": obj.posts.count(),
            "comment_count": obj.comments.count(),
        }

사용 기준

• Enum: 미리 정의된 선택지 그룹 (상태, 타입, 카테고리)

• TypedDict: 정해진 구조의 딕셔너리 데이터

주의사항: TypedDict는 런타임 강제가 아닌 정적 타입 검사와 문서화를 위한 도구