drf-yasg 또는 drf-spectacular로 Swagger 문서 자동화하기

API 개발하다 보면 Swagger 문서 작업이 정말 골치 아프죠. 일일이 수작업으로 작성하다 보면 시간도 오래 걸리고, 실수도 잦고… 그래서 저는 Django REST Framework(DRF)에서 Swagger 문서를 자동으로 만들어주는 DRF-Yasg랑 DRF-Spectacular 두 라이브러리를 써봤는데, 솔직히 후자가 훨씬 낫더라고요. 이 글에서 제 경험을 바탕으로 두 라이브러리를 비교해보고, DRF-Spectacular을 중심으로 사용법을 알려드릴게요. 자, 시작해볼까요?

먼저, 핵심 개념부터 간단히 짚고 넘어가죠. DRF-Yasg는 좀 오래된 친구인데, 안정적이고 많이 쓰이는 만큼 나름 장점이 있어요. 하지만 최신 OpenAPI 규격을 완벽하게 지원하지 않는 경우가 있고, 내가 원하는 대로 바꾸려면(커스터마이징) 좀 복잡할 수 있다는 단점이 있죠. 반면 DRF-Spectacular은 최신 라이브러리라서 OpenAPI 3.x 규격을 완벽하게 지원하고, 문서 생성도 훨씬 깔끔하고 직관적이에요. 사용하기도 쉽고, 내 마음대로 바꾸기도 편하죠. 단점이라면… 음… 아직 새로운 라이브러리라 가끔 버그를 만날 수도 있다는 점? 저는 아직 큰 문제는 없었지만요.

그럼 어떤 걸 써야 할까요? 솔직히 프로젝트 상황에 따라 다르지만, 저라면 최신 기능과 편의성을 중요하게 생각해서 DRF-Spectacular을 추천할 것 같아요. 안정성이 절대적으로 중요한 프로젝트라면 DRF-Yasg도 나쁘지 않겠지만요.

자, 이제 DRF-Spectacular을 실제로 사용하는 방법을 알려드릴게요. 설치는 pip install drf-spectacular 명령어 하나면 끝! 정말 쉽죠? 설치 후에는 settings.py 파일에 몇 줄만 추가하면 됩니다. 어려운 거 없어요, 그냥 따라 하세요! 설정 파일을 열고 다음 코드를 추가해 보세요. (설정 파일 위치는 프로젝트 구조에 따라 다를 수 있으니, 찾아보셔야 해요!)

INSTALLED_APPS = [
    # ... other apps ...
    'drf_spectacular',
    'rest_framework',
]

SWAGGER_SETTINGS = {
    'TITLE': 'My API',
    'DESCRIPTION': 'API documentation',
    'VERSION': '1.0.0',
}

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

TITLE, DESCRIPTION, VERSION 부분은 여러분의 API 정보에 맞게 바꿔주세요. 그리고 urls.py에도 몇 줄 추가해야 합니다. 이 부분은 꼭 기억해주세요!

from django.urls import path, include
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    # ... other urls ...
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
]

마지막으로 간단한 serializer와 view를 만들어서 테스트해볼게요. 여기서 MyModel은 여러분이 사용하는 모델로 바꿔야 합니다. 잊지 마세요!

from rest_framework import serializers, viewsets
from rest_framework.response import Response

class MyModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = MyModel # MyModel 은 적절한 모델을 대체해야 합니다.
        fields = '__all__'

class MyModelViewSet(viewsets.ModelViewSet):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer

이제 서버를 실행하고 /api/docs/ 에 접속하면 Swagger UI가 짠! 하고 나타날 거예요. 직접 API 문서를 확인해보세요. 신기하지 않나요?

몇 가지 주의할 점이 있는데요. 복잡한 모델이나 커스텀 필드가 있다면 schema_generator를 조금 손봐야 할 수도 있어요. 그리고 Swagger UI에서 API를 테스트하려면 인증(Authentication) 설정도 필요하고요. API가 너무 크다면 문서 생성 시간이 오래 걸릴 수 있으니 캐싱을 고려해보는 것도 좋습니다. 마지막으로 API 버전 관리도 중요해요. 버전 정보를 명확하게 표시해야 나중에 혼란을 막을 수 있답니다.

결론적으로, DRF-Yasg와 DRF-Spectacular 모두 장단점이 있지만, 개인적으로는 DRF-Spectacular이 훨씬 편리하고 효율적이라고 생각합니다. 특히 새로운 프로젝트를 시작한다면 DRF-Spectacular을 강력 추천해요! 더 자세한 내용은 각 라이브러리의 공식 문서를 참고하시면 좋습니다. 이 글이 여러분의 API 개발에 도움이 되었으면 좋겠네요! 궁금한 점 있으면 언제든지 물어보세요!