[Django-DRF] drf-yasg 를 활용한 Swagger 적용하기

앞선 글에서 REST API로 구성된 공지사항 CRUD를 작성 완료했다.

그러면 이제 작성한 API를 문서화시켜볼 건데, Spring에서 Swagger을 익숙하게 써 왔었기 때문에 찾아보던 중 Django도 Swagger를 지원해서 적용시켜보려고 한다.

 

 

이전 글

[Django-DRF] 커스텀 유저 모델 생성 및 회원가입 로그인 + JWT 적용

[Django-DRF] REST API를 이용한 CRUD 구현 with JWT, Pagination

 

 

 

---

 

 

공식문서를 참고 하면서 진행했다.

공식문서 주소는 : https://drf-yasg.readthedocs.io/en/stable/ 이곳이다.

 

drf-yasg 설치

pip install drf-yasg

위 명렁어로 설치부터 진행한다.

 

 

settings.py 수정

# settings.py

INSTALLED_APPS = [
    ...
    'django.contrib.staticfiles',  # required for serving swagger ui's css/js files
    'drf_yasg',
    ...
]

 

 

urls.py 수정

schema_view 쪽에 Swagger 기본 설정 즉, 이름이나 버전, 접근 가능한 권한 등을 기입해준다.

url도 접근이 가능하게끔 추가해준다.

# urls.py

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


schema_view = get_schema_view(
   openapi.Info(
      title="Snippets API",
      default_version='v1',
      description="Test description",
      terms_of_service="https://www.google.com/policies/terms/",
      contact=openapi.Contact(email="contact@snippets.local"),
      license=openapi.License(name="BSD License"),
   ),
   public=True,
   permission_classes=[AllowAny],
)

urlpatterns = [
   re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
   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'),
]

 

 

views.py 수정

이전 글에서 작성한 공지사항에 적용해보자 !

# notice/views.py

from django.shortcuts import get_object_or_404

from rest_framework import status
from rest_framework.response import Response
from rest_framework.decorators import api_view, permission_classes, authentication_classes
from rest_framework.permissions import IsAuthenticated, IsAdminUser, AllowAny
from rest_framework.pagination import PageNumberPagination
from rest_framework_simplejwt.authentication import JWTAuthentication

from notice.serializers import NoticeSerializer
from .models import Notice

from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi

page = openapi.Parameter('page', openapi.IN_QUERY, default=1,
                         description="페이지 번호", type=openapi.TYPE_INTEGER)
size = openapi.Parameter('size', openapi.IN_QUERY, default=5,
                         description="한 페이지에 표시할 객체 수", type=openapi.TYPE_INTEGER)


@swagger_auto_schema(
    method='post',
    operation_id='공지사항 등록',
    operation_description='공지사항을 등록합니다',
    tags=['Notice'],
    request_body=NoticeSerializer,
)
@api_view(['POST'])
@permission_classes([IsAuthenticated, IsAdminUser])  # 어드민 유저만 공지사항 작성 가능
@authentication_classes([JWTAuthentication])  # JWT 토큰 확인
def notice_create(request):
    serializer = NoticeSerializer(data=request.data)

    if serializer.is_valid(raise_exception=True):
        # 인증객체를 통해 인증을 진행하고 사용자 정보를 request.user 객체에 저장
        # 인증정보가 없거나 일치하지않으면 AnonymousUser를 저장
        serializer.save(user=request.user)
        return Response(status=status.HTTP_201_CREATED)


@swagger_auto_schema(
    method='get',
    operation_id='공지사항 조회',
    operation_description='공지사항 전체를 조회합니다',
    tags=['Notice'],
    manual_parameters=[page, size],
    responses={200: NoticeSerializer}
)
@api_view(['GET'])
@permission_classes([AllowAny])  # 글 확인은 로그인 없이 가능
def notice_list(request):
    notice_list = Notice.objects.all()
    paginator = PageNumberPagination()

    # 페이지 사이즈를 주면 해당 사이즈로 지정
    # 값이 없으면 기본 사이즈로 설정(settings.py안에)
    page_size = request.GET.get('size')
    if not page_size == None:
        paginator.page_size = page_size

    result = paginator.paginate_queryset(notice_list, request)
    serializers = NoticeSerializer(result, many=True)
    return paginator.get_paginated_response(serializers.data)

 

만약 POST에 request_body나 response를 커스텀 하고 싶다면

아래와 같이도 작성할 수 있다.

@swagger_auto_schema(
    method='post',
    operation_id='일반 회원가입',
    operation_description='회원가입을 진행합니다.',
    request_body=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        properties={
            'email': openapi.Schema(type=openapi.TYPE_STRING, description="이메일"),
            'password': openapi.Schema(type=openapi.TYPE_STRING, description="비밀번호"),
            'name': openapi.Schema(type=openapi.TYPE_STRING, description="이름"),
        }
    ),
    tags=['유저'],
    responses={200: openapi.Response(
        description="200 OK",
        schema=openapi.Schema(
            type=openapi.TYPE_OBJECT,
            properties={
                'access_token': openapi.Schema(type=openapi.TYPE_STRING, description="Access Token"),
                'refresh_token': openapi.Schema(type=openapi.TYPE_STRING, description="Refresh Token"),
            }
        )
    )}
)

 

 

확인

작성한 뒤 localhost:8000/swagger 로 접속하면

아래와 같이 깔끔하게 정리된 API 문서를 확인할 수 있다.

 

 

---

 

총 3개에 글에 거쳐서 장고의 기본적인 사용방법과 세팅법에 대해 알아보았다.

해당 내용들만 숙지하면 기본적인 Django의 REST API는 구현이 가능할 것이라고 생각한다.

 

프로젝트를 진행하면서 또 새롭게 배워 공유할만한 내용이 있다면 작성해보겠다.