[Django rest Framework] Swagger 문서 자동화 ( drf-yasg )

 

Swagger

REST API를 설계, 빌드, 문서화 및 사용하는데 도움이 되는 OpenAPI 사양을 중심으로 구축 된 오픈 소수 도구 세트입니다.

 

Django 프레임워크에서는 drf-yasg 라이브러리를 이용하여 python 코드로 더욱 쉽게 문서 자동화가 가능하다.

https://drf-yasg.readthedocs.io/en/stable/

drf-yasg — drf-yasg 1.20.1 documentation

https://github.com/axnsan12/drf-yasg/tree/master/testproj

GitHub - axnsan12/drf-yasg: Automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code.

 

왜 Swagger를 사용할까?

• 적용하기가 쉽다. Swagger는 코드 몇 줄만 추가하면 만들 수 있다는 장점이 있다.
• 테스트할 수 있는 UI를 제공한다. API를 바로바로 테스트할 수 있다는 장점이 있다.

 

Swagger 사용하기

 

먼저 drf-yasg 라이브러리를 설치한다. 물론 djangorestframework 라이브러리는 이미 설치되어있어야 한다.

$ pip install drf-yasg

 

그 다음은, settings.py의 ISNTALLED_APPS에 앞서 설치한 drf-yasg 라이브러리를 추가한다.

# settings/common.py (운영, 개발 개발환경 세팅을 하였기에 common.py에 공통적인 부분을 다 작성)

# ...

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

# ...

 

APP을 추가하였다면, base urls.py에서 Swagger 를 사용할 수 있도록 url을 추가해주어야 한다.

...
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi


# OpenAPI 정보 (필요한 정보만 사용하면 될듯)
schema_view = get_schema_view( 
    openapi.Info( 
        title="Swagger Study API", 
        default_version="v1", 
        description="Swagger Study를 위한 API 문서", 
        terms_of_service="https://www.google.com/policies/terms/", 
        contact=openapi.Contact(name="test", email="test@test.com"), 
        license=openapi.License(name="Test License"), 
    ), 
    public=True, 
    permission_classes=(permissions.AllowAny,), 
)


# Swagger, redoc 의 url
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'),
]

 

결과는 

 

이렇게 스웨거가 만들어졌다.