[Django] Function Based View 환경에서 Swagger 사용하기

Problem

---

Swagger를 추가해서 Django API 문서를 만들어보자

FBV(Function Based View) 환경에서 진행한다.

FBV 환경에서 진행하는 문서가 부족해 작성하게 되었다.

Solution

---

1. drf-yasg와 djangorestframework를 설치한다.

pip install drf_yasg
pip install djangorestframework

 

2. 설치 후 url.py에서 schema_url_patterns를 설정하고, get_schema_view를 정의한다.

schema_url_patterns = [
    path('루트URL/', include('app.url')),
]

schema_view_v1 = get_schema_view(
    openapi.Info(
        title="Open API",
        default_version='v1',
        description="시스템 API",
        terms_of_service="https://www.google.com/policies/terms/",
    ),
    public=True,
    permission_classes=(AllowAny,),
    patterns=schema_url_patterns,
)

 

3. settings.py 의 INSTALLED_APPS 에 설치한 라이브러리를 추가한다.

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    '앱',
    'drf_yasg',
    'rest_framework',
]

 

4. request 를 받는 Function Based View를 작성한다.

# 로그인 뷰
def login(request):
    if request.method == "POST":
    	...

 

5. 해당 View 위에 @api_view, @swagger_auto_schema 데코레이터를 추가해 Swagger에서 request 시 사용하는 인자값을 추가할 수 있다.

두 데코레이터를 import 한다.

from drf_yasg.utils       import swagger_auto_schema
from rest_framework.decorators import api_view

 

6. 데코레이터를 작성한다.

@api_view(['request 메소드', ...]) 를 통해 Swagger에서 어떤 메소드를 지원할 것인지,

@swagger_auto_schema(

    method = 'request 메소드',

    request_body = ...,

    responses={

       status 코드: ...,

    }

)

를 통해 각 메소드 별 request 시 필요한 인자와 response 시 제공하는 데이터를 작성한다.

 

ex) 만약 login 뷰가 POST 메소드를 사용하고, request body로 user_id와 user_pw가 필요하며, response로 error_code, error_message, data를 보내준다고 가정.

@swagger_auto_schema(
    method='post',
    request_body=openapi.Schema(	# request_body를 정의
        type=openapi.TYPE_OBJECT,	# OBJECT 타입임을 정의
        properties={				# request_body에 필요한 값을 정의
            'user_id': openapi.Schema(type=openapi.TYPE_STRING, description="유저ID"),
            'user_pw': openapi.Schema(type=openapi.TYPE_STRING, description="유저PW"),
        },),
    responses={						# responses 형식을 정의
    	200: openapi.Schema(
            type=openapi.TYPE_OBJECT, # OBJECT 타입임을 정의
            properties={			# responses 의 제공 값을 정의
                'error_code': openapi.Schema(type=openapi.TYPE_STRING, description="에러코드"),
                'error_message': openapi.Schema(type=openapi.TYPE_STRING, description="에러메시지"),
                'data': openapi.Schema(type=openapi.TYPE_STRING, description="데이터"),
            }
    	)
    }
)
@api_view(['POST'])					# 허용하는 METHOD를 정의
def login(request):
	if request.method == "POST":
    	...

각 데이터는 openapi의 Schema를 이용하여 정의한다. 

Schema에서는 해당 데이터의 type, 해당 데이터를 설명하는 description을 정의한다. 만약 Schema의 type이 TYPE_ARRAY 라면 해당 array가 어떤 type인지 알 수 있는 Schema를 items 필드에 정의해줘야 한다.

'array': openapi.Schema(type=openapi.TYPE_ARRAY, items=openapi.Schema(type=openapi.TYPE_STRING), description="array_type"),

 

7. swagger와 관련된 URL을 추가해준다.

 

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

 

8. 이제 runserver 후 http://127.0.0.1:8000/swagger에 접속하면 다음과 같이 문서가 출력된다.

 

Swagger 초기 화면

login View