Django - Swagger 연동하기 1편 - 기본 설정

안녕하세요.

글쓰는 개발자입니다.

 

  토이 프로젝트를 진행하면서 비록 혼자 진행하지만 최대한 현업 실무에 가깝게 또는 더 나아가 실무에 적용하고 싶은 기술과 방법론 등을 실험하고 있는데요. 그 중 하나로 Swagger를 적용하는 것을 소개하려고 합니다.

 저는 2022년 4월 현재, 1년 6개월의 개발 경력 중 세번 째 SI 프로젝트를 맡아서 진행하고 있습니다. SI 프로젝트를 진행하다보면 산출물로 문서를 많이 작성하게 되는데요. 문서 작성에 상당한 시간과 비용이 투입되는 것이 사실입니다. 그 중 저의 첫 번째 SI 프로젝트는 개발자만 약 30명 정도 투입되었는데요. API 문서화가 제대로 이루어지지 않아 커뮤니케이션 비용이 상당히 높았던 프로젝트 였습니다. 구글 스프레드시트에 일일이 Input/Output params와 example을 기록하고 개발하면서 변경되는 사항을 그 때마다 수작업으로 변경해야 했습니다.

 개발 초기에는 이것이 가능할지 몰라도 SI 프로젝트 특성상 잦은 기획 수정으로 인한 개발 일정 단축, 일정 압박 등의 이유로 API 문서 형상의 현행화가 이루어지지 않았고 이에 대한 대가 또한 개발자들이 모두 짊어져야 했습니다.

 당시에 '이건 뭐가 잘못 되었다.' 라는 생각이 들었던 저는 API 문서화에 대해 찾아보았고 오늘 소개 할 Swagger 가 많이 쓰인 다는 것을 알게 되었습니다. 똑같은 과오를 반복하고 싶지 않았기에 저 혼자 진행했던 두번째 프로젝트에 실험적으로 사용해 보고 이번 프로젝트에는 본격적으로 협업에 활용 중에 있습니다.

 이 글을 읽으시는 분들이 과거의 저와 저희 회사 동료들 처럼 미숙한 API 문서화에 따른 대가를 치르지 않길 바라며, Django - Swagger 연동과 제가 적용한 몇가지 방법에 관하여 소개드리고자 합니다.

 

 총 2편으로 작성 되며, 이 시리즈를 읽고 활용하시면 다음과 같은 기능을 사용하실 수 있습니다.

1편: django-swagger 기본 설정
     1. Django 프로젝트 기본 설정
     2. Django Rest Framework - APIView
     3. Django - Swagger 연동
2편: request / response schema 세팅
    4. Django - Swagger input/output params 지정
    5 참고. Input/Output params 지정시 serializer의 활용

 

1. Django 프로젝트 생성

먼저 Django 프로젝트를 생성합니다. 저는 django-project 라는 디렉토리를 생성하고 내부에 python 가상환경을 생성하고 활용해 package를 프로젝트별로 분리하여 관리하겠습니다.

 

1) 프로젝트 디렉토리 생성

mkdir django-project
cd django-project

2) 가상환경 생성

python3 -m venv venv
source venv/bin/activate

// windown 사용자 : source venv/Scripts/activate

3) Django 설치 - 프로젝트 생성

 django_swagger라는 이름으로 django-project를 생성합니다. 프로젝트 이름은 여러분들이 원하시는 이름으로 사용해도 됩니다. 예를 들어 django-admin project [여러분이 원하는 이름] 이런 식으로 말이죠.

pip install django
django-admin startproject django_swagger
cd django_swagger

4) Django Rest Framework 설치

pip install djangorestframework

5) Swagger 설치 (drf-yasg)

pip install drf-yasg

6) setting.py 설정

// django_swagger/settings.py

INSTALLED_APPS = [
		...
    'rest_framework',
    'drf_yasg',
		...
]

 

2. API 작성

 우리가 Swagger를 사용하는 목적은 Restful API를 작성하고 FrontEnd - Backend 개발자 간 협업 시 발생하는 커뮤니케이션 비용을 최소화 하고 API 문서화의 실천을 위함 입니다. 따라서 먼저 API를 작성해 보겠습니다.

 

1) django - app 생성

프로젝트 내부에서 비즈니스 로직을 수행 할 app을 생성하고 url을 연결 합니다. 지금 연결한 API를 swagger에서 보실 수 있습니다. 저는 임의로 sample_swagger라는 django-app을 생성하였는데요. django-app 이름은 여러분이 원하는 것으로 사용하셔도 상관 없습니다. 다만, 연동시 해당 명칭을 잘 확인해 주시기 바랍니다.

django-admin startapp sample_swagger

2) API 코드 작성

    테스트용 API를 sample_swagger/views.py 에 Django Rest Framework를 활용하여 API를 작성 하겠습니다. 참고로 APIView를 상속받으면, get, post, put, delete 함수를 통해 CRUD를 간편하게 사용할 수 있습니다.

// sample_swagger/views.py

from rest_framework import permissions
from rest_framework.views import APIView
from rest_framework.response import Response

# Create your views here.
class TestView(APIView):
    permission_classes = [permissions.AllowAny]

    def get(self, request):
        return Response("Swagger 연동 테스트")

3) sample_swagger 내부 urls.py 생성 ( sample_swagger/urls.py )

 Django를 처음 접하시는 분들을 위해 설명을 드리자면, django-app 내부에는 urls.py가 없습니다. 사용자가 직접 urls.py를 생성하고 이를 연결하는 방식을 통해 각각의 app 별로 url을 분리하여 사용할 수 있도록 합니다.

  sample_swagger/views.py에 생성한 TestView를 sample_swagger/urls.py에 적용합니다.

(아래 주석 처리된 코드 중 DefaultRouter는 현재는 필요가 없어서 주석처리 되었습니다.)

// sample_swagger/urls.py

from django.urls import path
#from rest_framework.routers import DefaultRouter
from sample_swagger.views import TestView

# Create a router and register our viewsets with it.
# router = DefaultRouter()

# The API URLs are now determined automatically by the router.
urlpatterns = [
    path('v1/test/', TestView.as_view(), name='test'),
]

그리고 추가한 sample_swagger/urls.py 정보를 django_swagger/urls.py에 추가합니다.

// django_swagger/urls.py

from django.contrib import admin
from django.urls import include, path, re_path

urlpatterns = [
    path('admin', admin.site.urls),
    path('api/', include(('sample_swagger.urls', 'api'))),
]

4) Swagger 세팅 (django_swagger/urls.py)

 Swagger 를 적용하기 위해 django_swagger/urls.py에 Swagger 관련 내용을 아래와 같이 추가 합니다. 내용이 많아서 어렵게 느껴지실 수도 있는데요. 간단히 읽어보면 라이센스와 descriptions 관련된 내용이니 크게 신경쓰시지 않아도 되는 내용입니다.

// django_swagger/urls.py

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

router = routers.DefaultRouter()

schema_view = get_schema_view(
    openapi.Info(
        title="Statchung API",
        default_version='v1',
        description="Test description",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="contact@snippets.local"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=[permissions.AllowAny],
)

# Wire up our API using automatic URL routing.
# Additionally, we include login URLs for the browsable API.
urlpatterns = [
    path('admin', admin.site.urls),
    path('api/', include(('sample_swagger.urls', 'api'))),
]

if settings.DEBUG:
    urlpatterns += [
        re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
        re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
        re_path(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
    ]

 

3. Django - Swagger 연동 확인

 

1) Django 실행

python manage.py runserver

2) Swagger 접속

Chrome 브라우저 주소창에 http://127.0.0.1:8000/swagger/ 를 입력하여 아래와 같이 위에서 생성하고 설정한 Test API가 정상적으로 나타나는지 확인합니다.

http://127.0.0.1:8000/swagger/

우리가 TestView에서 작성하고 urls.py 설정한 GET 방식의 /api/v1/test/ API를 확인 할 수 있습니다. 그리고 아래와 같이 Try out을 통해 API를 실행 할 수 있습니다. Response Body를 보시면, status code 200 과 "Swagger 연동 테스트"를 제대로 Response하고 있있습니다.

 

 여기까지 Django, Django Rest Framework, drf-yasg를 활용한 Django-Swagger 기본 세팅 작업을 마쳤습니다. 이제 협업을 위한 가장 기본 세팅을 마쳤다고 할 수있는데요. 하지만 Swagger 적용의 목적이 커뮤니케이션 비용 최소화 였듯이 Input/Output param을 정의하고 볼 수 있어야 제대로 된 세팅이라 할 수 있는데요. 이는 다음 편에서 마저 설명하도록 하겠습니다. 끝까지 잘 따라와 주셔서 진심으로 감사드립니다.

 

Refference

drf-yasg
Django Rest Framework APIView