Django에서 Swagger로 API 문서화하기

명확하고 최신의 API 문서는 어떤 프로젝트에서든 필수입니다. 특히 다른 개발자와 협업하거나, 외부 서비스와 통합하거나, 오랜 시간 동안 API를 유지보수할 때 더욱 중요하죠. Swagger(현재는 OpenAPI로 알려짐)는 가장 널리 사용되는 API 문서화 표준 중 하나이며, Django에서는 drf-yasg 또는 drf-spectacular 같은 패키지를 통해 쉽게 통합할 수 있습니다.

이 가이드에서는 Django 프로젝트에 Swagger UI를 설정하고, 자동으로 아름답고 인터랙티브한 API 문서를 생성하는 방법을 소개합니다.

서론

API 문서를 수동으로 작성하는 것은 시간이 많이 들고 오류가 발생하기 쉽습니다. Swagger와 같은 도구는 Django REST Framework의 뷰와 시리얼라이저를 기반으로 문서를 자동 생성해줍니다. 덕분에 코드와 문서의 불일치 문제를 방지할 수 있습니다.

이 글에서는 drf-yasg를 사용하여 Django에 Swagger를 설정하는 과정을 안내합니다.

1. 필수 패키지 설치

다음 명령어로 Swagger 통합 라이브러리를 설치하세요:

pip install drf-yasg

그리고 settings.py의 INSTALLED_APPS에 'rest_framework'와 해당 앱을 추가하세요.

 

2. urls.py에 Swagger 설정

프로젝트의 메인 urls.py 파일에서 다음과 같이 스키마 뷰를 설정합니다:

from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
from django.urls import path, re_path

schema_view = get_schema_view(
    openapi.Info(
        title="My API",
        default_version='v1',
        description="API documentation for my Django project",
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    re_path(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]

이제 브라우저에서 /swagger/ 또는 /redoc/에 접속하면 인터랙티브한 API 문서를 확인할 수 있습니다.

 

3. API 메타데이터 커스터마이징

openapi.Info 객체를 수정하여 연락처, 라이선스, 서비스 약관 등의 추가 메타데이터를 포함할 수 있습니다:

openapi.Info(
    title="My Custom API",
    default_version='v2',
    description="자세한 API 설명 작성",
    contact=openapi.Contact(email="dev@example.com"),
    license=openapi.License(name="MIT License"),
)

 

4. DRF 뷰에서 자동 문서 생성

Swagger는 DRF의 뷰, 시리얼라이저, 모델 필드를 읽어 자동으로 문서를 생성합니다. @swagger_auto_schema 데코레이터를 활용하면 문서를 더욱 풍부하게 만들 수 있습니다:

from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    operation_description="게시글 리스트 조회",
    responses={200: PostSerializer(many=True)}
)
def get(self, request):
    ...

이렇게 하면 설명과 응답 스키마가 문서에 명확하게 나타납니다.

 

5. 프로덕션 환경에서 Swagger 접근 제한

개발 환경에서는 매우 유용하지만, 운영 환경에서는 Swagger UI 접근을 제한하는 것이 좋습니다. 환경 설정이나 로그인 제어로 접근을 차단하세요.

예시:

if settings.DEBUG:
    urlpatterns += [
        re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0)),
    ]

 

마치며

drf-yasg를 통해 Django 프로젝트에 Swagger를 통합하면 API 문서를 손쉽고 전문적으로 관리할 수 있습니다. 인터랙티브한 문서는 사용성과 개발 속도를 높이고, 팀 간의 의사소통 오류를 줄여줍니다.

여러분은 Django에서 Swagger를 사용해본 적 있으신가요? 경험이나 궁금한 점이 있다면 댓글로 공유해 주세요—더 나은 API 협업 환경을 함께 만들어 봅시다!

 

Django 모델링: 데이터베이스 설계의 핵심