[Django] Swagger를 이용한 API Documentation

 

 

Swagger와 drf-yasg

`Swagger`는 API 문서를 쉽고 간단하게 만들도록 도와주는 오픈 소스 도구이다. 

`drf-yasg`는 Django Rest Framework API로 Swagger/OpenAPI 2.0 Specification을 생성해 주는 라이브러리이다. 공식 문서는 이 글을 참고하자. 

 

drf-yasg 사용 방법

Notice  CBV에서 적용

 

작업하는 가상 환경에서 아래 명령어를 입력하여 `drf-yasg`를 설치한다. 

$ pip install -U drf-yasg

 

설치가 완료되었다면 `settings.py`에 아래 코드를 작성하자.

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

 

swagger UI의 css/js 파일이 필요하면 아래 코드로 작성한다.

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

 

그 다음 `urls.py`에 아래 코드를 작성한다.

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

...

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=(permissions.AllowAny,),
#    authentication_classes=[]  # settings.py의 REST_FRAMEWORK > DEFAULT_AUTHENTICTION_CLASSES 가 적용되어 있다면 추가해줄 것
)

urlpatterns = [
   path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
   path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
   path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
   ...
]

위처럼 다 작성한다면 이제 swagger URL에 접근할 수 있게 된다.

 

swagger는 API를 JSON이나 YAML 형식으로 내보낼 수 있게 한다. JSON으로 내보내고 싶다면 위에 적은 `urls.py`의 `urlpatterns` 부분을 아래처럼 작성하면 된다.

urlpatterns = [
    path('swagger.json/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
    ...
]

이렇게 작성하고 브라우저에서 URL로 접근하면 JSON 파일이 다운로드된다. `Postman`에도 JSON이나 URL을 이용하여 API를 import 할 수 있다.

 

다 작성하고 나면, 최종적으로 아래 URL로 접근할 수 있게 된다.

• IP:PORT/swagger/
• IP:PORT/redoc/
• IP:PORT/swagger.json/

이 정도만 해도 swagger에 접속하면 만든 API들을 확인할 수 있다. 

localhost:8000/swagger/ 접속 화면

 

localhost:8000/redoc/ 접속 화면