DRF API Document drf-spectacular

왜 drf-spectacular 인가?

나는 처음 drf doc api를 찾아보면서 drf-yasg와 django-rest-swagger 가 주로 많이 언급 되었었는데 drf-yasg가 특히나 많은 사람들이 사용하는 것 같아서 drf-yasg로 진행하였다. 

 

하지만 사용할 수록 불편함이 많았고 OpenAPI 3.0도 지원하지 않는 다는 것을 알았다. 그래서 찾아 보다가 drf-spectacular를 찾게 되었다.

 

drf-spectacular는 2020년 3월에 첫 릴리즈된 drf의 openAPI 3.0을 지원하는 유일한 오픈소스이다.

 

drf-spectacular의 장점

1. swagger UI의 버전과 설정값들이 drf-spectacular의 버전에 의존하지 않는다.
   • drf-spectacular는 라이브러리 자체를 버전업 하지 않더라도 settings 값을 조절하면 최신 버전의 swagger-ui를 사용할 수 있다.
2. swagger UI 자체에서 제공하는 UI 커스터 마이징 옵션들을 자유롭게 조절이 가능하다.

 

 

drf-spectacular 설정

라이브러리 설치

pip install djangorestframework # 만약 drf가 설치되어 있지 않으면 설치
pip install drf-spectacular  # pip을 사용하면 이렇게 설치

 

settings.py 수정

# settings.py

INSTALLED_APPS = [
    # ...
    'rest_framework',
    'drf_spectacular',
    # ...
]

REST_FRAMEWORK = {
    # YOUR SETTINGS  drf의 schema 클래스를 drf-specacular의 AutoSchema로 교체해줍니다.
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

 

urls.py 수정

from django.contrib import admin
from django.urls import path
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView


urlpatterns = [
    path("admin/", admin.site.urls),

    # Open API 자체를 조회
    path('api/docs/', SpectacularAPIView.as_view(), name='schema'),

    # Open API Document UI로 조회: Swagger, Redoc
    path('api/docs/swagger/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('api/docs/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

 

 

drf-specatcular settings 설정

Settings — drf-spectacular documentation

위 링크를 읽어보고 설정값을 본인이 원하는 내용으로 수정하면 된다.

아래는 내가 커스터마이징한 설정값이다.

SPECTACULAR_SETTINGS = {
    'TITLE': 'Obab-project',
    'DESCRIPTION': "Obab API 문서입니다.</br>"
                   "토큰 인증을 하실 때는 헤더에 'Token xxx' 형태로 액세스 토큰에 Token(Bearer) 접두사를 붙여주세요.</br>"
                   "로컬에서 개발하실 때에는 하단의 HTTP 스키마를 선택해 주시고, 실제 서버에서는 HTTPS 스키마를 선택해 주세요.",
    'SWAGGER_UI_SETTINGS': {
        'dom_id': '#swagger-ui',
        'layout': 'BaseLayout',
        'deepLinking': True,
        'persistAuthorization': True,
        'displayOperationId': True,
        'filter': True,
    },
    'LICENSE': {
        'name': 'Git Hub',
        'url': 'https://github.com/O-BAB/obab-server',
    },
    'SCHEMA_PATH_PREFIX': r'/api/v[0-9]',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
}

 

 

결과

완성된 swagger 캡처본

 

 

Reference

Django Rest Framework API Document Generator (feat. drf-spectacular)

drf-spectacular — drf-spectacular documentation