[Django rest framework] 번외. swagger 적용하기

 

 

 

 API 문서는 프로젝트를 수행하는 규모와 방식에 따라 각기 다른 목적으로 다양한 문서를 작성하게 됩니다. 수많은 프로젝트에서 그렇듯 이런 문서는 조금만 방심하면 유지보수되지 않는 문서가 되곤 합니다.

 여러가지 이유로 유지보수되지 않는 문서로 인해 발생하는 유산(legacy)은 가끔(거의 항상) 프로젝트에 악영향을 주곤 합니다. 그중에 API 문서에 대해 공유해보려 합니다.

 

 

앞서 만든 API들을 다른 개발자분들과 함께 사용하기 위해선 문서가 필요합니다.

자동으로 문서화를 해줄 package는 drf-yasg를 사용합니다.

 

drf-yasg 패키지 설치

$ pip3 install drf-yasg

 

settings.py 설정

#settings.py

INSTALLED_APPS = [
   ......
    "drf_yasg",
]

 

urls.py 에 swagger 링크 추가

# urls.py

from django.urls import path, include
from rest_framework.documentation import include_docs_urls

docs_view = include_docs_urls(
    title='drf API',
    description='API document'
)



urlpatterns += [
   path('docs/', docs_view),
]

 

DRF swagger 결과 화면

 

 

 

drf 페이지에 권한 적용 하기  (어드민 사용자만 허용하기)

- 만일 모든 사용자가 아닌 특정 사용자에게만 페이지를 보여주고 싶다면 drf의 permission_classes를 이용해서 권한을 넣어주면 됩니다.

- 어드민 권한이 있는 유저만 보고 싶다면, 아래와 같이 IsAdminUser를 넣어주면 됩니다.

.............
from rest_framework.permissions import IsAdminUser
..............


docs_view = include_docs_urls(
    title='drf API',
    description='API document',
    permission_classes=[IsAdminUser]
)

 

 

API 문서 자동화에 사용할 주석 작성

- 따로 API 별 주석이 필요할 경우 아래와 같이 주석을 추가합니다.

- 공통 API는 사용하는 모든 메소드에 공통으로 들어갑니다.

- 만일 해당 메소드에 주석이 있다면 공통 주석 대신 들어갑니다.

# views.py

class UserView(viewsets.ModelViewSet):
    """
    공통 API 설명은 여기에
    """
    ...............
    
    def list(self, request):
        """
        list 관련 내용은 여기에
        """
		..................

 

주석의 결과화면은 다음과 같습니다.

 

참고 자료

- gaussian37.github.io/python-rest-drf-yasg/

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