DJango 서버개발, Django REST Framework에서 API 문서화 도구 (Swagger, CoreAPI) 사용하기

Django는 파이썬 기반의 웹 프레임워크로서, 강력하고 유연한 백엔드 서버 개발을 가능하게 합니다. Django REST Framework (DRF)는 Django에 RESTful API를 쉽게 구현할 수 있도록 도와주는 도구입니다. 그러나 API의 문서화는 종종 간과되는 부분이며, 이는 API의 사용성을 저하시킬 수 있습니다. 이에 따라 Swagger와 CoreAPI와 같은 API 문서화 도구를 사용하는 방법을 살펴보겠습니다.

1. Django REST Framework 소개

Django REST Framework는 Django로 RESTful API를 쉽게 구축할 수 있게 해주는 고급 라이브러리입니다. 이 라이브러리는 다음을 제공합니다:

직관적인 API 설계
강력한 인증 시스템
유연한 시리얼라이징
다양한 필터링 옵션
문서화 지원

이러한 기능 덕분에 DRF를 사용하면 복잡한 API를 보다 쉽게 구축할 수 있습니다.

2. API 문서화의 중요성

API 문서화는 API의 사용법을 명확히 하고, 외부 개발자 또는 팀원들이 API를 효율적으로 사용할 수 있도록 하는 중요한 과정입니다. 잘 문서화된 API는:

사용자 교육을 용이하게 합니다.
버그를 줄일 수 있습니다.
개발 속도를 높입니다.
기타 팀원 간의 소통을 원활하게 합니다.

3. Swagger와 CoreAPI 소개

Swagger는 API 문서화를 위한 가장 널리 사용되는 도구 중 하나입니다. Swagger UI는 API를 시각적으로 보여주고, 사용자들이 요청을 테스트할 수 있는 기능을 제공합니다. 반면, CoreAPI는 DRF와 자연스럽게 통합되어 API 문서화 및 테스트를 쉽게 해줍니다.

3.1 Swagger

Swagger는 API 문서와 테스트 도구를 제공합니다. Swagger를 사용하면 다음과 같은 장점을 누릴 수 있습니다:

사용자 친화적인 UI 제공
API 요청/응답 테스트
API 문서 자동 생성

3.2 CoreAPI

CoreAPI는 RESTful API의 문서화 및 테스트를 위한 더 경량화된 옵션입니다. DRF와의 통합이 용이하며, API 사양을 정의할 수 있는 간단한 문법을 제공합니다. 핵심 기능으로는 다음이 있습니다:

간단한 사용법
API 문서 자동화
완성도 높은 스펙

4. Django 프로젝트에 Swagger 및 CoreAPI 설정하기

Swagger와 CoreAPI를 Django 프로젝트에 통합하는 과정은 아래와 같은 단계로 진행됩니다.

4.1 설정 준비

먼저 기본적인 Django 프로젝트와 Django REST Framework가 설치되어 있어야 합니다. 필요한 패키지를 설치합시다:

pip install djangorestframework
pip install drf-yasg  # Swagger 문서화를 위한 패키지
pip install coreapi  # CoreAPI 이용을 위한 패키지

4.2 Django settings 구성

Django 프로젝트의 settings.py에 다음과 같이 추가합니다:

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

4.3 Swagger 설정 예제

Swagger를 설정하기 위해 urls.py에 다음 코드를 추가합니다:

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="My API",
      default_version='v1',
      description="API 설명서",
      terms_of_service="https://www.google.com/policies/terms/",
      contact=openapi.Contact(email="contact@myapi.local"),
      license=openapi.License(name="BSD License"),
   ),
   public=True,
   permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    ...
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
]

4.4 CoreAPI 설정 예제

CoreAPI를 사용하기 위한 설정은 좀 더 간단합니다. urls.py에 다음 코드를 추가합니다:

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    path('docs/', include_docs_urls(title='My API title')),
]

5. API 문서화 예제

이제 간단한 API를 만들어 문서화를 테스트해 보겠습니다. 간단한 메모리 저장소 API를 만들어 보겠습니다.

5.1 모델 정의

먼저, API를 위한 모델을 정의합니다. models.py에 아래와 같이 작성합니다:

from django.db import models

class Note(models.Model):
    title = models.CharField(max_length=100)
    content = models.TextField()

    def __str__(self):
        return self.title

5.2 시리얼라이저 정의

모델과 연결될 시리얼라이저를 생성합니다. serializers.py를 생성하거나 사용하여 아래와 같이 작성합니다:

from rest_framework import serializers
from .models import Note

class NoteSerializer(serializers.ModelSerializer):
    class Meta:
        model = Note
        fields = '__all__'

5.3 뷰 정의

API의 로직을 정의할 뷰를 만들어야 합니다. views.py를 수정하여 아래와 같이 작성합니다:

from rest_framework import viewsets
from .models import Note
from .serializers import NoteSerializer

class NoteViewSet(viewsets.ModelViewSet):
    queryset = Note.objects.all()
    serializer_class = NoteSerializer

5.4 URL 패턴 정의

이제 API의 URL 패턴을 설정합니다. urls.py에 아래와 같이 작성합니다:

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import NoteViewSet

router = DefaultRouter()
router.register(r'notes', NoteViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

6. API 테스트 및 문서화

모든 설정이 완료되었습니다. Django 서버를 실행하고 http://localhost:8000/swagger/ 또는 http://localhost:8000/docs/에 접속하여 API 문서화 상태를 확인해보세요. 각 엔드포인트에서 제공하는 API 문서와 함께 요청을 테스트할 수 있습니다.

7. 결론

Django REST Framework와 Swagger, CoreAPI를 사용하여 API 문서화를 효율적으로 진행할 수 있습니다. 이러한 도구들은 개발자의 생산성을 높이고, 다른 사용자에게도 유용한 정보를 제공합니다. 프로젝트의 복잡성이 증가함에 따라 API 문서화는 점점 더 중요해지며, 따라서 이러한 도구들을 적극적으로 활용하는 것이 좋습니다.

8. 추가 자료

더 읽어보기: