Django

[Django] API 문서화

monster route 2024. 9. 10. 03:32

API 문서화

 

API 문서의 경우, 사실 회사마다 다르고 개발팀마다 사용하는 방법이 다르다. 각 회사마다 다르고 팀마다 다르고 사용하는 툴도. 형식도 다르다. 로마에 가면 로마의 법을 따르듯, 문서도 아마 조직에 맞는 형식을 따르게 될 거다. 

 

대표적으로 가장 많이 쓰이는 문서 형식들을 살펴보자. 

 

  • 노션(Notion)

IT 업계에서 소통을 위한 도구로 많이 사용하는 도구다.

검색, 필터, 정렬등 데이터를 편하게 작성하고 볼 수 있는 기능을 제공한다.

https://teamsparta.notion.site/659a433196e84d619cbdaa2121efacfe?v=fd64cd963d064df1913fef419a50cf7a&pvs=4

 

 

  • 포스트맨(Postman)

Postman과 함께 제공되는 경우가 일반적이므로 문서도 포스트맨에 작성하는 경우가 많습니다.

간편한 테스트와, 결과 저장이 가능해 편리하다는 장점이 있습니다.

 

 

이 밖에도 많은 툴들이 있다.

  • Git Book
  • 엑셀(Excel)
  • 워드(Word)
  • …

API 문서의 장점 및 한계점

  • 우리 조직에 맞게 완벽하게 커스텀해서 작성 가능
  • 작성툴에 대한 학습 없이 누구나 작성 및 수정 가능
  • 코드가 변경될 때 마다 문서를 수정해주지 않으면 문서의 가치를 상실함

 

여기서 나온 고민이 바로 "내 코드를 기반으로 API 문서를 만들도록 할 수 없을까?" 🤔

 

 

그래서, 우리가 사용하는 Django REST Framework 는 내가 작성한 코드를 기반으로 문서를 작성해주는 도구 두가지를 제공한다. 👀

1. drf-spectacular
2. drf-yasg 

 

 

🔖공식문서 

 

Documenting your API - Django REST framework

 

www.django-rest-framework.org

RESTful API는 자원에 대한 표현과 접근하는 방법을 잘 정의하는 것이 가장 중요하며, 이에 대한 자세한 설명과 명확한 정의가 필요하다고 한다.

 

 

  • drf-spectacular & drf-yasg
    • 둘 모두 코드를 기반으로 API Doc을 만들고, 이 문서를 사용자가 보기 편하게 UI로 변환하는 도구(Swagger-UI / Redoc)를 포함하고 있음
    • 둘의 가장 큰차이는 drf-yasg 는 OpenAPI 2 기반으로 만들어졌고 drf-spectacular 는 OpenAPI 3을 기반으로 한다는 것

 

  • OpenAPI?
    • OAS(OpenAPI Specification)이 정식명칭
    • RESTful API를 설명하고 표현하는 하나의 표준
    • 프로그래밍 언어에 한정되지 않도록 RESTful API를 인터페이스화 하려는 방향. 즉, 사용자 또는 프로그램이 소스코드나 글로 작성된 문서를 보지 않고도 서비스의 기능들을 이해할 수 있도록 JSON 형태로 표현하려는 프로젝트
    • OAS를 지원하는 Swegger 또는 Redoc을 이용하면 JSON으로 작성된 API Doc을 보기편한 UI로 변환할 수 있다

 

 

 

🔖 공식문서

Django REST Framework을 위한 합리적이고 유연한 OpenAPI 스키마 생성기

 

 

 

설치 및 셋팅

 

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',
    ...
}

 

 

프로젝트 폴더의 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'),
]

 

 

 

~/api/schema/swagger-ui/ 로 접근해보면, 내가 작성한 코드 기반으로 문서가 생성된 것을 볼 수 있다👍

 

 

 

이대로 완벽하면 참 좋겠지만 (그렇지 않다..🫠)

 

 

 

@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)
...

 

 

@extend_schema(
        tags=["Articles"],
        description="Article 생성을 위한 API",
        request=ArticleSerializer,
)
def post(self, request):
    serializer = ArticleSerializer(data=request.data)
    if serializer.is_valid(raise_exception=True):
        serializer.save()
        return Response(serializer.data, status=status.HTTP_201_CREATED)

 

 

그럼 이제 해결이 된걸까? 🤔

 

그럴수도 있고, 아닐수도 있다..  Spectacular를 이용해서 코드를 기반으로한 문서화를 적용해도, 실사용을 위해서는 많은 커스텀이 필요하다. 또한 문제없이 동작하더라도 View로직 코드 보다 문서화를 위한 코드가 더 길어지는 상황이 오기도 하고 커스텀 자체가 일이되어 다른 툴로 되돌아오는 경우가 생기기도 한다.

 

즉, 쓰고자 하는 도구에 대해 잘 이해하고, 내부 문서와 코드를 뜯어보며 나에게 또는 우리 팀에게 잘 맞는 가장 효율적인 방법을 찾아야 한다.