-
[Django] API 문서화Django 2024. 9. 10. 03:32
API 문서화
API 문서의 경우, 사실 회사마다 다르고 개발팀마다 사용하는 방법이 다르다. 각 회사마다 다르고 팀마다 다르고 사용하는 툴도. 형식도 다르다. 로마에 가면 로마의 법을 따르듯, 문서도 아마 조직에 맞는 형식을 따르게 될 거다.
대표적으로 가장 많이 쓰이는 문서 형식들을 살펴보자.
- 노션(Notion)
IT 업계에서 소통을 위한 도구로 많이 사용하는 도구다.
검색, 필터, 정렬등 데이터를 편하게 작성하고 볼 수 있는 기능을 제공한다.
- 포스트맨(Postman)
Postman과 함께 제공되는 경우가 일반적이므로 문서도 포스트맨에 작성하는 경우가 많습니다.
간편한 테스트와, 결과 저장이 가능해 편리하다는 장점이 있습니다.
이 밖에도 많은 툴들이 있다.
- Git Book
- 엑셀(Excel)
- 워드(Word)
- …
API 문서의 장점 및 한계점
- 우리 조직에 맞게 완벽하게 커스텀해서 작성 가능
- 작성툴에 대한 학습 없이 누구나 작성 및 수정 가능
- 코드가 변경될 때 마다 문서를 수정해주지 않으면 문서의 가치를 상실함
여기서 나온 고민이 바로 "내 코드를 기반으로 API 문서를 만들도록 할 수 없을까?" 🤔
그래서, 우리가 사용하는 Django REST Framework 는 내가 작성한 코드를 기반으로 문서를 작성해주는 도구 두가지를 제공한다. 👀
1. drf-spectacular
2. drf-yasg🔖공식문서
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로직 코드 보다 문서화를 위한 코드가 더 길어지는 상황이 오기도 하고 커스텀 자체가 일이되어 다른 툴로 되돌아오는 경우가 생기기도 한다.
즉, 쓰고자 하는 도구에 대해 잘 이해하고, 내부 문서와 코드를 뜯어보며 나에게 또는 우리 팀에게 잘 맞는 가장 효율적인 방법을 찾아야 한다.
'Django' 카테고리의 다른 글
[Django] 뉴스 API 서버 구현 중, 트러블 슈팅 (7) 2024.09.14 Django DRF 개인과제 트러블 슈팅 (0) 2024.09.10 [Django] AWS 배포 → Gunicorn, Nginx 설치 및 설정 (2) 2024.09.08 Django, AWS 배포 (Deploy) (2) 2024.09.06 Django 외부 API 연동하기 (1) 2024.09.05