DJango + Swagger 연동 진행 방법

여는 글

어제 진행하고 있던 입학상담 챗봇 프로젝트에 Swagger를 연동하였다.

난 API를 중점 개발 하는 역할이며 프론트 팀과 협업을 하는 중이기에 프론트 쪽에서

Swagger로 API작성을 하는게 어떤지 권유받았기 때문이다.

생각보다 너무 잘 되어있어서 놀랐고 이제까지 노션이라 POSTMan으로 api를 작성했었는데

앞으로는 Swagger만 사용할 것 같다.. 좋은 것을 또 배운다.

 

Swagger는 API 문서화와 테스트를 쉽게 할 수 있도록 도와주는 도구이다.

개발자들이 API를 설계, 구축, 문서화, 소비하는 과정을 단순화하는 역할을 한다.

Swagger는 기본적으로 RESTful API를 시각적으로 표현하고 이해하기 쉽게 만들어 준다.

Swagger를 사용하면 API의 기능을 쉽게 확인하고, 테스트할 수 있으며, 자동으로 문서화를 생성할 수 있다.

Swagger는 OpenAPI Specification(OAS)이라는 표준을 기반으로 작동한다.

이 표준은 API의 구조를 정의하는 명세서로, API의 엔드포인트, 요청 및 응답 형식, 파라미터 등을 설명한다.

 

그럼 Swagger를 어떻게 장고 프로젝트에 적용하고 사용할 수 있는지 확인해보자

 

 

DJango + Swagger 연동 방법

1. swagger 설치

pip install drf-yasg

 

2. drf 설치

pip install djangorestframework

 

3. settings.py에 추가

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "maruegg",
    "accounts",
    'drf_yasg',
    'rest_framework',
]

 

4. 본 프로젝트 urls.py에 세팅

from django.contrib import admin
from django.urls import include, path
from django.views.generic import TemplateView
from django.conf.urls.static import static
from django.conf import settings
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg       import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="프로젝트이름(ex: test-project)",
        default_version='프로젝트버전(ex: 0.1',
        description="문서 설명(ex: 무슨무슨 api입니다.)",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="이메일"),
        license=openapi.License(name="mit"),
    ),
    public=True,
    permission_classes=[permissions.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'),
    # main
    path("admin/", admin.site.urls),
    path("maruegg/", include("maruegg.urls")),
    path("accounts/", include("accounts.urls")),
    path("", TemplateView.as_view(template_name="base.html"), name="root"),
]
urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

=> 다음과 같이 프로젝트의(app의 urls.py가 아님) urls.py에 스키마 뷰를 정의해주고

=> url패턴에 상위 3개 path를 그대로 복붙해주면 된다.

 

5. 서버 실행 및 확인

=> 본인 주소/swagger로 접속하니 잘 출력된다!

 

DJango + Swagger 사용방법

이제 본인이 생성한 app의 views.py에 들어와서 테스트로 코드를 작성해보자

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

@swagger_auto_schema(
    method='post',
    manual_parameters=[
        openapi.Parameter(
            'string_value',
            openapi.IN_QUERY,
            description='String value to be processed',
            required=True,
            type=openapi.TYPE_STRING
        )
    ],
    responses={200: 'Success', 400: 'Invalid request'}
)
@api_view(['POST'])
@csrf_exempt
def test(request):
    if request.method == "POST":
        received_value = request.query_params.get("string_value", "")
        logger.debug(f"Received value: {received_value}")
        if received_value:
            return JsonResponse({"message": "요청이 잘 들어왔습니다", "received_value": received_value}, status=200)
        return JsonResponse({"error": "string_value is required"}, status=400)
    return HttpResponse("Invalid request", status=400)

=> 먼저, drf_yasg.utils에서 swagger_auto_schema를, drf_yasg에서 openapi를 임포트한다.

이 두 모듈은 Swagger 문서화를 위한 주요 도구이다.

swagger_auto_schema 데코레이터는 API 뷰에 대한 스웨거 스펙을 정의하는 데 사용되며, openapi.Parameter는 API의 파라미터를 정의하는 데 사용된다.

다음으로, @swagger_auto_schema 데코레이터를 사용하여 POST 메소드에 대한 문서를 작성한다. 

manual_parameters 옵션을 사용해 API가 받을 파라미터를 정의한다.

여기서는 string_value라는 이름의 문자열 파라미터를 정의했다.

이 파라미터는 쿼리 파라미터로 전달되고 필수 값이다.

responses 옵션을 사용해 가능한 응답 상태 코드를 정의한다. 나는 200(성공)과 400(잘못된 요청)을 정의했다.

 

swagger_auto_schema 데코레이터 API 뷰에 대한 Swagger 스펙을 정의하는 데 사용된다. 메소드, 파라미터, 응답 등을 설정할 수 있다.

openapi.Parameter API가 받을 파라미터를 정의하는 클래스이다. 파라미터의 이름, 위치, 설명, 필수 여부, 타입 등을 설정할 수 있다.

api_view 데코레이터 Django REST framework의 데코레이터로, 특정 HTTP 메소드를 지원하는 뷰를 정의할 때 사용된다.

csrf_exempt 데코레이터 CSRF 검사를 비활성화하는 Django 데코레이터이다.

 

=> 접속해서 값을 넣고 테스트 해보니 정상적으로 테스트까지 진행된다!

 

swagger는 앞으로 계속 사용할 것 같다. 좋은 스택을 또 배워간다.

 

참고문서

https://velog.io/@max-sum/Django-Swagger-기본편