[파이썬] Django REST 프레임워크를 이용한 Swagger 문서화

01 Sep 2023

python

Django REST 프레임워크는 파이썬 기반의 웹 프레임워크인 Django를 확장하여 RESTful API를 쉽게 개발할 수 있는 도구입니다. 이 프레임워크를 이용하면 API를 설계하고 문서화하는 과정을 간소화할 수 있습니다. Swagger는 RESTful API의 설계, 빌드, 문서화, 소비를 지원하는 강력한 도구입니다. Django REST 프레임워크와 Swagger를 함께 사용하면 개발 프로세스를 더욱 효율적으로 진행할 수 있습니다.

Swagger란?

Swagger는 API 개발 프로세스를 단순화하고 문서화하는 데 사용되는 오픈 소스 프로젝트입니다. Swagger는 API의 구조, 요청 및 응답에 대한 세부 정보를 제공하며, 이를 기반으로 클라이언트 개발자가 API를 손쉽게 이해하고 사용할 수 있도록 도와줍니다. Swagger는 API 디자인 시스템이라고도 불리며, 개발자들이 API를 쉽게 공유하고 협업할 수 있도록 돕습니다.

Django REST 프레임워크와 Swagger의 결합

Django REST 프레임워크는 Swagger와의 통합을 지원하여 API를 문서화하는 프로세스를 자동화할 수 있습니다. django-rest-swagger라이브러리는 Django REST 프로젝트의 API를 Swagger UI를 통해 시각화하고, interative한 API 문서를 생성해줍니다. 이를 통해 개발자는 클라이언트 API의 작동 방식을 이해하는 데 도움을 받을 수 있으며, API를 쉽게 테스트할 수 있습니다.

Django REST 프레임워크에서 Swagger 문서화 설정하기

다음은 Django REST 프레임워크와 Swagger를 통합하여 API를 문서화하는 방법입니다:

Django REST 프레임워크와 django-rest-swagger 라이브러리를 설치합니다.
```
 pip install djangorestframework
 pip install django-rest-swagger
```

settings.py 파일에 다음 설정을 추가합니다:

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

 REST_FRAMEWORK = {
     'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
 }

urls.py 파일에 다음 경로를 추가합니다:

 from rest_framework_swagger.views import get_swagger_view

 schema_view = get_swagger_view(title='API 문서')

 urlpatterns = [
     ...
     path('api-docs/', schema_view),
 ]

실행 중인 서버에 접속하여 http://{your_domain}/api-docs/ 경로로 이동합니다. Swagger UI를 통해 자동 생성된 API 문서를 확인할 수 있습니다.

Swagger 문서화 예제

다음은 Django REST 프레임워크와 Swagger를 통해 문서화된 API의 예제입니다:

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.documentation import renderers

class HelloView(APIView):
    renderer_classes = [renderers.OpenAPIRenderer, renderers.SwaggerUIRenderer]

    def get(self, request):
        """
        API에 대한 기본 설명입니다.
        """
        content = {'message': '안녕하세요!'}
        return Response(content)

위의 예제에서 APIView 클래스를 상속하여 HelloView를 생성합니다. get 메소드에는 API에 대한 설명을 작성할 수 있습니다. renderer_classes 속성은 SwaggerUIRenderer를 이용하여 문서를 시각화합니다.

결론

Django REST 프레임워크와 Swagger의 결합은 API 개발 프로세스를 효율적으로 관리하고 문서화하는 데 도움을 줍니다. Swagger를 통해 생성된 API 문서는 개발자들에게 API를 이해하고 사용하는 데 필요한 정보를 제공하며, 클라이언트 개발자와의 협업을 용이하게 합니다. Django REST 프레임워크와 Swagger를 함께 사용하여 API를 개발하고 문서화하는 과정을 더욱 효율적으로 진행할 수 있습니다.