Django Restful API 문서를 작성하기(feat. drf-yasg)

 

django rest api를 문서화 하자!

 

django restframework를 이용해서 RestAPI를 만들었다.

프론트 혹은 다른 사람과 원활한 소통을 위한 문서 작업을 했다.

swagger 보다 drf-yasg가 문서적으로 더 보기에 좋은것 같아서 이를 이용했다. 

자동으로 되는 부분이 많은 만큼 이해가 않되는 부분이 있지만 당장 빠르게 사용하기에는 충분한거 같아서 이를 사용했다.

 

 

• Install

pip install -U drf-yasg
pip install flex

 

• settings.py에 APP추가

INSTALLED_APPS = [
	...
	'drf_yasg',
]

 

• yasg.py 생성 후 내용 입력

 

• urls.py에 바로 넣어도 되지만 urls.py에 내용이 너무 길어지기 때문에 분리 시켰다.

from django.conf.urls import url
from django.urls import path, include
from drf_yasg.views import get_schema_view
from rest_framework.permissions import AllowAny, IsAuthenticated, BasePermission
from drf_yasg import openapi

schema_url_patterns = [
    path('boards/', include('boards.urls')),
]
 
schema_view = get_schema_view(
    openapi.Info(
        title="하하호호 Open API",
        default_version='v1',
        description = 
        '''
        하하호호 Open API 문서 페이지 입니다.

        하하호호는 취미 모임을 만들어주는 웹입니다.
        
        팀원: ...
        ''',
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="test@gmail.com"),
        license=openapi.License(name="하하호호"),
    ),
    validators=['flex'],
    public=True,
    permission_classes=(AllowAny,),
    patterns=schema_url_patterns,
)

 

 

• urls.py 에 내용추가

from .yasg import *

urlpatterns = [
    ...
    
    path('swagger<str: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('docs/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]

 

 

• 실행 화면
• /docs/에 접속하면 아래의 이미지가 나온다.

 

 

• 커스텀 하기
• 타이틀과 API설명들을 추가하기
  • class 바로 밑에 내용을 적는다.
  • ''' 와 ''' 사이에 글을 작성한다.
  • 첫 문장을 작성하고 띄어쓰기를 해야 첫 문장이 제목처럼 보일 수 있다.
  • --- 를 이용해서 줄을 그어 문단을 구분 시킬 수 있다.

• 코드 예시

 

 

• 커스텀하기 
• 결과 예시 이미지는 아래와 같다.

 

 

 

 

 

 

---

Reference

https://jay-ji.tistory.com/31

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