API 문서화

Web

API 문서화

서영환 2024. 9. 6. 09:36

지금 까지 개발한 내용을 Front 쪽 개발자들에게 전달하기 위해서는 구두 혹은 문서로 전달을 해야 한다. 그런데 작은 규모의 회사의 경우를 제외한 일반적인 회사 및 프리랜서또는 개발한 내용을 상용화 하여 다른 개발자들에게 전달하기에는 구두로는 한계가 있다.

그렇기게 API 문서를 따로 작성하여 전달하는게 일반적이다.

그렇다면 이때까지 개발한 API 문서를 어떻게 만드는 것일까?

API 문서를 만들때에는 다양한 방법으로 문서를 만 들 수 있다. 그 중 일반적으로 많이 사용하는 3가지에 대해 구술을 하려한다.

1. 노션

IT 업계에서 소통을 위한 도구로 많이 사용하 도구로, 검색, 필터, 정렬등 데이터를 편하게 작성하고 볼 수 있는 기능을 제공

2. 포스트맨(Postman)

포스트맨과 함께 제공되는 경우가 일반적이므로 문서도 포스트맨에 작성하는 경우가 많고, 간편한 테스트와 결과 저장이 가능해 편리하다라는 장점이 있지만 2인 이후부터는 유료이다.

3. DRF-Spectacular

1,2 번 모두 코드가 변경 될 때마다 문서를 수정해 주지 않으면 문서가 가치를 상실한다. 이러한 문제를 해결 하기 위하여 Django REST Framework에서는 DRF-Spectacular or DRF-Yasg를 제공하고 있다.

둘은 모두 코드릴 기반으로 API Doc을 만들고, 이문서를 사용자가 보기 편하게 UI로 변환하는 도구(Swagger-UII.Redoc)를 포함하고 있다

둘의 차이는 DRF-Yasg는 OpenAPI 2 기반으로 제작되었고 DRF-Spectacular는 OpenAPI 3 기반으로 제작 되었다

설치 및 셋팅

pip install drf-spectacular

# settings.py
INSTALLED_APPS = [
    ...
    'drf_spectacular',
]

REST_FRAMEWORK = {
    ...
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

SPECTACULAR_SETTINGS = {
    'TITLE': 'MY Django API',
    'DESCRIPTION': 'Django DRF API Doc',
    'VERSION': '1.0.0',
    ...
}


# Project in urls.py
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView

urlpatterns = [
    # YOUR PATTERNS
    ...
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    # Optional UI:
    path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]


# App in views.py
# @extend_schema 데코레이터를 이용해서 문서를 커스터마이징 할 수 있다.
...
class ArticleListCreateAPIView(APIView):
    permission_classes = [IsAuthenticated]

    @extend_schema(
        tags=["Articles"],
        description="Article 목록 조회를 위한 API",
    )
    def get(self, request):
        articles = Article.objects.all()
        serializer = ArticleSerializer(articles, many=True)
        return Response(serializer.data)
...