django rest framework swagger drf_yasg 설정 #10

API 문서화를 위해 **Swagger(drf-yasg)**를 적용하면,

API 요청/응답을 한눈에 확인하고 테스트할 수 있다.

 

이 글에서는 Django REST Framework에서 Swagger를 설정하는 방법을 단계별로 설명한다.

 

✅ Swagger 설치하기

 

📍 1. 가상환경 활성화

 

터미널에서 Django 프로젝트의 가상환경을 활성화한다.

source venv/bin/activate  # Mac/Linux
venv\Scripts\activate     # Windows

 

📍 2. drf-yasg 패키지 설치

 

아래 명령어를 실행하여 drf-yasg를 설치한다.

pip install drf-yasg

 

📌 설치가 완료되면 아래와 같은 메시지가 출력된다.

#swagger 설치코드
#작업 중인 파이썬 가상환경으로 이동한다.
#명령어는 pip install drf-yasg

(pubd_api) pubdapi % ls
db.sqlite3	manage.py	pubdapi		pubdapp
(pubd_api) pubdapi % pip install drf-yasg
.....
.....
.....
Installing collected packages: pytz, uritemplate, pyyaml, packaging, inflection, drf-yasg
Successfully installed drf-yasg-1.21.7 inflection-0.5.1 packaging-24.1 pytz-2024.1 pyyaml-6.0.1 uritemplate-4.1.1
(pubd_api) pubdapi %

 

🔗 공식 설치 가이드:

https://drf-yasg.readthedocs.io/en/stable/readme.html#installation

 

✅ settings.py에서 Swagger 설정

 

설치가 완료되면, Django 설정 파일에 Swagger를 추가해야 한다.

 

📍 INSTALLED_APPS에 drf_yasg 추가

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'corsheaders',
    'pubdapp',
    'drf_yasg',  # Swagger 추가
]

 

✅ urls.py에서 Swagger 설정

 

urls.py 파일에 Swagger의 기본 설정을 추가한다.

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

# Swagger 기본 설정
schema_view = get_schema_view(
   openapi.Info(
      title="공공데이터 포털 API",
      default_version='v1',
      description="국회도서관 자료검색 API",
      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,),
)

# URL 패턴 추가
urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('rest_framework.urls')),
    path('api/pubd/', include('pubdapp.urls')),  # 공공데이터 포털 API URL
    path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),  # JSON 형식 API 문서
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),  # Swagger UI
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),  # ReDoc UI
]

 

📌 Swagger UI 접속 경로

✅ Swagger 문서 보기: http://localhost:8000/swagger/

✅ ReDoc 문서 보기: http://localhost:8000/redoc/

✅ JSON Schema 확인: http://localhost:8000/swagger.json

 

✅ views.py에서 API 문서 작성하기

 

Swagger 문서는 각 API 엔드포인트의 요청/응답 구조를 설명하는 주석을 추가해야 한다.

from django.shortcuts import render
from rest_framework.response import Response
from rest_framework.decorators import api_view, permission_classes
from rest_framework.permissions import AllowAny
from .api import nanet_api
from .models import Nanet
from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi

@swagger_auto_schema(
    method='get',
    operation_description='국회도서관 자료검색 API',
    operation_summary='국회도서관 자료검색 API',
    manual_parameters=[
        openapi.Parameter('ServiceKey', openapi.IN_QUERY, description='서비스키', type=openapi.TYPE_STRING),
        openapi.Parameter('search', openapi.IN_QUERY, description='검색어', type=openapi.TYPE_STRING),
        openapi.Parameter('pageno', openapi.IN_QUERY, type=openapi.TYPE_NUMBER, description='페이지 번호'),
        openapi.Parameter('displaylines', openapi.IN_QUERY, type=openapi.TYPE_NUMBER, description='페이지 Rows'),
    ],
    responses={200: 
        openapi.Response(
            description="200 OK",
            schema=openapi.Schema(
                type=openapi.TYPE_OBJECT,
                properties={
                    'resultCode': openapi.Schema(default="00", description="결과코드", type=openapi.TYPE_STRING),
                    'resultMsg': openapi.Schema(type=openapi.TYPE_STRING, default="OK", description="결과메시지"),
                    'total': openapi.Schema(type=openapi.TYPE_STRING, description="전체 결과 수"),
                    'name': openapi.Schema(type=openapi.TYPE_STRING, description="디스플레이 카테고리명"),
                    'value': openapi.Schema(type=openapi.TYPE_STRING, description="디스플레이 데이터"),
                }
            )
        )
    }
)
@api_view(['GET'])
@permission_classes([AllowAny])
def nanet_search(request):    
    """ 국회도서관 자료 검색 API """
    
    param = []
    test = []
    
    # 파라미터 받기
    param.append(request.GET.get('search'))  # 검색어
    param.append(request.GET.get('pageno'))  # 페이지 번호
    param.append(request.GET.get('displaylines'))  # 한 페이지당 결과 수
    
    # API 호출 로그 생성
    if param[0] is not None:
        create_nanet_log(param)
    else:
        test.append('자체 테스트중')
        test.append(1)
        test.append(10)
        create_nanet_log(test)
        
    # 공공데이터 API 함수 호출
    res = nanet_api(param)    
  
    return Response(res)

# nanet 로그 생성 함수
def create_nanet_log(param):
    nanet_save = Nanet(search=param[0], pageno=param[1], displaylines=param[2])
    nanet_save.save()

 

📌 Swagger 적용 후의 API 문서 예제

http://localhost:8000/swagger/ 에 접속하면,

아래처럼 자동으로 생성된 API 문서를 확인할 수 있다.

 

✅ Swagger 문서 확인

 

설정을 마친 후, Django 서버를 실행한다.

python3 manage.py runserver

 

이후 웹 브라우저에서 아래 주소에 접속하면,

Swagger UI에서 API 요청/응답을 확인하고 테스트할 수 있다.

 

🔗 Swagger UI: http://localhost:8000/swagger/

 

📌 실행 결과 예시

django rest framework swagger 설치

django rest framework swagger 설치

 

✅ 마무리

 

이제 Django REST Framework에서 Swagger 문서를 자동 생성할 수 있다! 🎉

 

✅ Swagger 적용 완료

✅ API 요청/응답 문서 자동화

✅ Swagger UI를 통해 API 테스트 가능

 

📌 다음 글 예고

🔗 지금까지 작성한 코드를 테스트하기 위한 테스트 코드 작성하여

API 호출테스트로 코드의 안정성을 확보할 수 있도록 해보겠다. 🚀