drf-yasg을 이용하여 swagger 문서 자동화 하기

이번 글은 django restframework를 이용해 API를 만들 때, 이걸 잘 설명하는 문서화를 자동으로 만드는 방법에 대해 알아보려 한다.

자동으로 문서화를 해주는 package는 drf-yasg 이다.

구글링을 통해 drf-yasg를 많이 추천하였고 간단히 어떻게 사용하는지에 대해 알아보려고 한다.

패키지 설치

pip install -U drf-yasg
pip install flex

1. drf-yasg : API를 자동 문서화 해주는 패키지
2. flex : JSON schema를 체크하는 검사 패키지
   • JSON은 좀 더 쉽게 데이터를 교환하고 저장하기 위하여 만들어진 데이터 교환 표준입니다.
   • 이때 JSON 데이터를 전송받는 측에서는 전송받은 데이터가 적법한 형식의 데이터인지를 확 인할 방법이 필요합니다.
   • 따라서 적법한 JSON 데이터의 형식을 기술한 문서를 JSON 스키마(schema)라고 합니다.

환경 설정

• project/settings.py 의 INSTALLED_APPS에 추가

INSTALLED_APPS = [
   ...
   'drf_yasg',
   ...
]

• 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_url_v1_patterns = [
    url(r'^sample/v1', include('sample.urls', namespace='sample')),
]
 
schema_view_v1 = get_schema_view(
    openapi.Info(
        title="sample API",
        default_version='v1',
        description="This is the sample API for something",
        contact=openapi.Contact(email="service.sample@google.com"),
        license=openapi.License(name="sample company"),
    ),
    validators=['flex'],
    public=True,
    permission_classes=(AllowAny,),
    patterns=schema_url_v1_patterns,
)

urlpatterns = [
    ...
    url(r'^sample/v1/', include('sample.urls', namespace='sample_api')),
    ...
    
    # API document generation with  drf_yasg
    url(r'^v1/swagger(?P<format>\.json|\.yaml)/$', schema_view_v1.without_ui(cache_timeout=0), name='schema-json'),
    url(r'^v1/swagger/$', schema_view_v1.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    url(r'^v1/redoc/$', schema_view_v1.with_ui('redoc', cache_timeout=0), name='schema-redoc-v1'),
    ...
]

• urls.py에 코드가 너무 길게 들어가는게 보기가 좋지 않은 경우

schema_url_v1_patterns = [
    url(r'^sample/v1', include('sample.urls', namespace='sample')),
]
 
schema_view_v1 = get_schema_view(
    openapi.Info(
        title="sample API",
        default_version='v1',
        description="This is the sample API for something",
        contact=openapi.Contact(email="service.sample@google.com"),
        license=openapi.License(name="sample company"),
    ),
    validators=['flex'],
    public=True,
    permission_classes=(AllowAny,),
    patterns=schema_url_v1_patterns,
)

이 부분을 따로 떼어내어 import 시키는 것을 권장한다.

API 문서 자동화에 사용할 주석 작성

• API 문서 자동하에 사용될 내용은 주석을 기반으로 작성한다.
• DRF의 Viewset 함수의 class 바로 아래 또는 각 method 바로 아래에 작성하면 된다.
• 각 함수 바로 앞에 주석을 사용하면 그 내용을 바탕으로 markdown 형식으로 입력한다.

# example
class SampleViewSet(viewsets.ModelViewSet):
    '''
    Sample 관련 REST API 제공
    
    ---
    ... 내용 ...
    '''
    

    def list(self, request, *args, **kwargs):
        '''
        Sample의 list를 불러오는 API
        
        ---
        ... 내용 ...

위와 같이 class 바로 아래 또는 method 바로 아래에 작성하면 되고 주의할 점은

• 주석의 제목을 적고 : Sample 관련 REST API 제공
• 한 줄 띄우고
• 칸을 나누는 ---를 입력하고 그 아래에
• 내용을 적는다. : … 내용 …

API 문서 자동화 결과 보기

앞에서 url 설정 후 다음과 같은 url을 입력해 주었다.

url(r'^v1/swagger(?P<format>\.json|\.yaml)/$', schema_view_v1.without_ui(cache_timeout=0), name='schema-json'),
url(r'^v1/swagger/$', schema_view_v1.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
url(r'^v1/redoc/$', schema_view_v1.with_ui('redoc', cache_timeout=0), name='schema-redoc-v1'),

즉, redoc과 swagger라는 페이지가 각각 존재한다.

• redoc은 문서화에 좀 더 충실한 페이지이므로 문서화 목적으로 알맞은 페이지다.
• swagger는 API를 호출할 수 있다.
  

참고 자료 :
http://jay-ji.tistory.com/31
https://medium.com/towncompany-engineering/%EC%B9%9C%EC%A0%88%ED%95%98%EA%B2%8C-django-rest-framework-api-%EB%AC%B8%EC%84%9C-%EC%9E%90%EB%8F%99%ED%99%94%ED%95%98%EA%B8%B0-drf-yasg-c835269714fc
https://gaussian37.github.io/python-rest-drf-yasg/