django swagger (drf-yasg)

rest api 문서 자동화를 위해 swagger를 사용했습니다.

1. swagger 설치

pip install -U drf-yasg
pip install flex

스웨거 공식문서에는
pip install django-rest-swagger 를 install 하라고 해서 찾아보니,
django-rest-swagger 은 패키지 관리가 잘 안되고 있는 것 같습니다.
그래서 drf-yasg 를 install 해줍니다.

flex : JSON schema를 체크하는 패키지

2. settings.py 에 설정하기

# settings.py
INSTALLED_APPS = [
    'drf_yasg',  # 추가하기 
]

여기서 오전 시간을 다 썼는데, 모든 설정을 다 했는데도 런타임에러가 났었습니다.
'django.contrib.auth' 부분을 제가 주석 처리 해놨었어서 이 부분이 주석이 되어 있다면 꼭! 풀어주셔야 합니다.

# 프로젝트 > urls.py

from django.urls import path, include, re_path
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
from django.conf import settings
from rest_framework.permissions import AllowAny
from rest_framework import routers, permissions


schema_view = get_schema_view(
    openapi.Info(
        title="project A title", # 타이틀
        default_version='v1', # 버전
        description="프로젝트 API 문서", # 설명
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="이메일"),
        license=openapi.License(name=""),
    ),
    validators=['flex'],
    public=True,
    permission_classes=(AllowAny,)
)


urlpatterns = [
    path(r'swagger(?P<format>\.json|\.yaml)', schema_view.without_ui(cache_timeout=0), name='schema-json'),
    path(r'swagger', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    path(r'redoc', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc-v1'),
    # django 앱 
    path('scooter', include('scooter.urls')),
    path('bus', include('bus.urls'))
]

프로젝트 urls.py에서 위와 같이 설정해주고 나서
런서버 > http://localhost:8000/swagger 에 접속해도 내가 짠 api들이 나오지 않았습니다.

3. views.py 에 데코레이터 작성하기

저는 get해오는 과정에서 파라미터가 있는 상황이었기 때문에 아래와 같이 스키마를 작성해주었습니다.
만약, 파마리터가 따로 없다면, class 와 def 사이에 있는 두 줄은 안 적으셔도 됩니다.

from rest_framework.views import APIView
from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi


class Test(APIView):
    bstopId = openapi.Parameter('stationId', openapi.IN_QUERY, description='정류소 고유번호', required=True, default=165000381, type=openapi.TYPE_NUMBER)
    
    @swagger_auto_schema(manual_parameters=[bstopId], responses={200: "Success"})
    def get(self, request):
        bstopId = request.GET.get("stationId", None)

클래스형 뷰를 사용했기 때문에, class 와 함수 사이에 swagger_auto_schema 데코레이터 를 작성해주면 된다.

4. View vs APIview

처음에는 위와 같이 설정하고 나서도, api들이 나오지 않았습니다.
확인해보니 ,

class Test(View):

그냥 View 로 했을 때는 스웨거에 api가 나오지 않았고,

class Test(APIView):

APIView로 바꿔주니 스웨거에 api가 나왔습니다.

Schemas

• API schema는 참조 문서를 생성하거나 API와 상호 작용 할 수 있는 동적 클라이언트 라이브러리를 구동하는 등 다양한 사용 사례를 허용하는 유용한 도구입니다.
• REST 프레임워크의 스키마 생성은 docstring을 사용하여 스키마 문서의 설명을 자동으로 채웁니다.
• 명시적인 메서드 docstring이 있는 APIView입니다.
  참고

결과적으로 그냥 View가 아닌 APIView로 바꿔줘야 api문서가 완성 됩니다.