[django] swagger로 REST API 문서 만들기

인트로

안녕하세요 :D

오늘은 장고에서 Swagger를 활용하여 REST API Doc을 만들어 보겠습니다.

swagger는 프로젝트 내 많은 API를 한꺼번에 문서화하여 볼 수 있게 하는 패키지로, API 관리에 매우 용이합니다.

Swagger를 사용하기 위해서는 drf-yasg , djangorestframework를 설치하여 사용할 예정입니다.

drf-yasg는 장고로 정의된 API를 문서화할 수 있는 패키지로, (django rest framework- Yet another Swagger generator)의 약자입니다.  그럼 swagger 를 사용 환경을 세팅하여, Rest API 문서를 열어보겠습니다. 

* 프로젝트 환경 (프로젝트명 : testproject / 앱명 : blog / FBV)

목차
1. 라이브러리 설치
2. settings.py 추가 
3. urls.py 추가 
4. API 데코레이터 추가 

 

1. 라이브러리 설치

먼저 장고 Swagger를 사용하기 위해서는 drf-yasg, djangorestframework 두 가지가 필요합니다. 

장고 REST API를 위해 아래 두 라이브러리를 설치합니다.

REST란? Reperesentational State Transfer의 약자로, SW 아키텍처의 한 형식입니다. URL만 요청하면 특정 파일 형식으로 데이터를 반환하기 때문에 요청 플랫폼에 종속적이지 않고, 확장성이 좋아 많이 사용되고 있습니다. REST와 많이 쓰이는 형식은 SOAP(Simple Object Access Protocol) 인데 , 대부분의 레거시 시스템에서 많이 사용되고 있습니다. 

pip install drf-yasg
pip install djangorestframework

 

2. setting.py 추가

settings.py의 INSTALLED_APPS 에 아래 두 패키지를 추가합니다.

INSTALLED_APPS = [
    'drf_yasg', #drf_yasg
    'rest_framework', #djangorestframework
]

 

3. urls.py 추가

urls.py에는 아래와 같이 3단계에 걸쳐 추가합니다. (본 글 최하단에 전체 코드가 있습니다)

1. get_schema_view/openapi/AllowAny  import

urls.py에는 아래와 같이 get_schema_view/openapi/AllowAny 등을 import합니다. 

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

 

 

2. schema_url_patterns 정의 

schema_url_patterns에는 swagger에서 API 문서로 보고싶은 URL들을 정의합니다. 

schema_url_patterns = [ 
    path('', include('blog.urls')),
    ]

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. urlpatterns 정의 

swagger를 보기 위한 엔드포인트를 정의합니다. 

urlpatterns = [
    path('admin/', admin.site.urls),
    path('',include('blog.urls')),
    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'),
]

 

그리고 로컬 서버를 돌려 http://127.0.0.1:8000/swagger/ 에 접속하면 아래와 같은 화면이 뜹니다. 

 

4. API 데코레이터 추가

DRF(django rest framework)에서는 요청한 request구분을 API 데코레이터를 통해 구분합니다. 

제 장고 프로젝트는 FBV(Function Based View) 이기 때문에, API 데코레이터인 @api_view(['GET'])으로 선언해 주어야 swagger에서 인식합니다.  저와 같은 FBV 기반 프로젝트는 @api_view 데코레이터를 사용하여 API 뷰를 짜야 하며, CBV 기반 프로젝트는 APIView 클래스를 사용하여  API 뷰를 짜야 합니다 :D 

urls.py

from django.urls import path
from . import views

app_name='blog'
urlpatterns = [
    path('/get_url',views.get, name = 'get'),
    path('/post_url',views.post, name = 'post'),
]

 

views.py

from django.shortcuts import render
from rest_framework.decorators import api_view #api
from rest_framework.response import Response #api

@api_view(['GET'])
def get(request) : 
    return Response(request)

    
@api_view(['POST'])
def post(request) : 
    return Response(request)

 

urls.py와 views.py를 입력하고 서버를 돌려 로컬 주소로 들어갑니다.

URL : http://127.0.0.1:8000/swagger/ 

아래와 같이 내가 선언한 메소드들이 API 문서화되어 있는 것을 볼 수 있습니다 :D

 

첨부) urls. py 전체 코드 

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

schema_url_patterns = [ 
    path('', include('blog.urls')),
    ]

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,
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('',include('blog.urls')),
    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'),
]