swagger의 존재를 알고 있었지만 지금까지는 API를 많이 만들어내지 않아서 API 문서 자동화의 필요성을 크게 느끼지 못했다.
하지만 최근들어 API를 계속해서 만듦으로써 자동화가 필요하여 swagger를 공부하였다.
drf-yasg란?
django-rest-swagger는 오류가 많이 발생하고 패키지를 더이상 관리하지 않는다고 하여 drf-yasg를 추천한다고 한다.
django-rest-swagger와 똑같은 API문서 자동화 패키지 이다.
1. 설치하기
pip install -U drf-yasg # API 문서 자동화 패키지 pip install flex # JSON schema를 체크하는 검사기 패키지
여기서 JSON schema란 JSON 데이터를 전송 받는 측에서 전송받은 데이터가 적법한 형식의 데이터인지를 확인할 방법이 필요한데 적법한 JSON 데이터의 형식을 기술한 문서를 JSON schema 라고 한다.
2. settings.py 내 INSTALLED_APPS에 추가하기
INSTALLED_APPS = [
'drf_yasg'
]django 에서 기본으로 제공해주는 기능인 django.auth 기능을 사용하지 않아 주로 주석처리를 하는데, swagger를 사용하기 위해서는 django.contrib.auth를 주석 해제해야 한다.
주석처리 해놓은 상태로 돌리면 Runtime error가 발생한다.
3. urls.py 설정하기
from django.conf.urls import url
from drf_yasg.views import get_schema_view
from rest_framework.permissions import AllowAny
from drf_yasg import openapi
schema_view_v1 = get_schema_view(
openapi.Info(
title="제목 작성",
default_version='v1',
description="설명 작성",
terms_of_service="https://www.google.com/policies/terms/",
contact=openapi.Contact(email="본인 이메일 작성"),
license=openapi.License(name=""),
),
validators=['flex'],
public=True,
permission_classes=(AllowAny,),
patterns=schema_url_v1_patterns,
)
urlpatterns = [
# 기존 작성했던 Endpoint는 유지하고 아래 세줄 추가하기
url(r'^swagger(?P<format>\.json|\.yaml)/v1$', schema_view_v1.without_ui(cache_timeout=0), name='schema-json'),
url(r'^swagger/v1/$', schema_view_v1.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
url(r'^redoc/v1/$', schema_view_v1.with_ui('redoc', cache_timeout=0), name='schema-redoc-v1'),
]4. views.py 설정하기
기존
class TagView(View): def get(self,request): . . .
변경
from rest_framework.views import APIView from drf_yasg.utils import swagger_auto_schema from drf_yasg import openapi위 세줄 임포트 후
class TagView(APIView): def get(self,request): . . .View -> APIView로 변경해주기
5. 완성된 swagger 살펴보기
-
runserver 돌리기
-
http://localhost:8000/swagger 을 통해 접속한다.
API 문서가 자동화 된 채로 나온 것을 확인할 수 있다.
6. swagger 커스터마이징 하기
class 와 def 사이에 주석처리를 하면 swagger에 알맞게 나온다.
빨간색 칠해놓은 곳은 줄바꿈을 해야 swagger에 이쁘게 적용 될 수 있다.
etc 1. 토큰 추가하기
settings.py 내에서 밑 코드를 추가하고
SWAGGER_SETTINGS = {
'SECURITY_DEFINITIONS': {
'DRF Token': {
'type': 'apiKey',
'name': 'Authorization',
'in': 'header'
}
}
}swagger에 들어간다.
오른쪽 상단에 Authorize 버튼을 누르고 Value 값에 토큰을 넣어주면 인증이 된다.
etc 2. body 추가하기
serializer를 만들어 body에 들어가야 할 것들을 model 적듯이 적어준다.
class ContactForm(serializers.Serializer):
notification = serializers.IntegerField()views.py에 swagger_auto_schema를 데코레이터로 달아준 후 아까 만들었던 serializer를 부른다.
class NotificationLikeView(APIView):
@swagger_auto_schema(request_body=ContactForm)
@login_required
def post(self,request):
.
.
.
etc 3. 쿼리 파라미터 추가하기
앞선 body추가하기와 똑같이 serializer를 만들어 모듈화 한다. (서버에서 받아야 할 query parameter들)
tag = serializers.IntegerField(help_text="태그 필터링", required=False)
page = serializers.IntegerField(help_text="페이지", default=1, required=False)
search = serializers.CharField(help_text="검색어", required=False)views.py에 swagger_auto_schema를 데코레이터로 달아준 후 아까 만들었던 serializer를 부른다.
class NotificationView(APIView):
@swagger_auto_schema(query_serializer=NotificationSerializer)
def get(self,request):
.
.
.
etc 4. 패스 파라미터 추가하기
쿼리 파라미터와 굉장히 유사하다.
class DetailSerializer(serializers.Serializer):
notification_id = serializers.IntegerField(help_text='공고 PK', required=True)똑같이 serializer 모듈화 시킨 후
class NotificationDetailView(APIView):
@swagger_auto_schema(path_serializer=DetailSerializer)query_serializer가 아닌 path_serializer로 변경하면 끝
