ABOUT ME

-

Today
-
Yesterday
-
Total
-
  • [Django] API 문서화
    Django 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로직 코드 보다 문서화를 위한 코드가 더 길어지는 상황이 오기도 하고 커스텀 자체가 일이되어 다른 툴로 되돌아오는 경우가 생기기도 한다.

     

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

     

     

     

Designed by Tistory.