Django REST Framework에서 API 문서 자동화하기

jacoblee19·4일 전
1

Django REST Framework

목록 보기
9/9
post-thumbnail

지금 감사하게도 몇 군데 면접을 보고 있다. 오프라인에서 면접을 바로 본 회사도 있었고, 코딩 테스트를 보내주는 회사도 있고, 그리고 코딩 과제라고 해서 API를 만들어야 되는 회사도 있었다.

Django REST Framework를 기반으로 API를 만들어가고 있는데 요구 사항에 API 문서 자동화가 필수 구현 사항이라서 DRF에서 API 문서 자동화를 어떻게 하는지 한 번 알아보려 한다.

API 문서 자동화

우선 API 문서를 왜 만들어야하고, 또 자동화가 왜 필요한지 이론적인 부분을 알아보았다.
Swagger 공식 웹사이트 내용을 보면, 다음과 같이 나와있다.

A critical component to providing a great developer experience is providing accurate 
and up-to-date API documentation. 
API documentation is the information that is required to successfully consume and 
integrate with an API. 
This could be in the form of technical writing, code samples, and examples for better 
understanding how to consume an API.

훌륭한 개발자 경험을 제공하기 위한 결정적인 부분은 바로 정확한 최신의 API 문서를 제공하는 것이다.
API 문서란 성공적으로 API를 사용하고 접목하기 위해 필요한 정보이다.
이 것들은 테크니컬 라이팅, 코드 샘플, 또 어떻게 API를 사용할지 더 나은 이해를 위한 예시 같은 형태로 제공된다.

캐나다에 있을 때 가끔 technical writer를 채용하는 것을 본 적 있는데, 보면서도 무슨 직업일까 했는데, 요번 기회에 약간 알 수 있었던 것 같다.

그럼 바로 drf에서 API 문서 자동화 하는 방법을 알아보자.

drf-yasg

우선 설치법은 공식 사이트에서 확인 가능하다.
drf-yasg 공식 사이트

먼저 pip를 통해 drf-yasg를 설치한다.

pip install drf-yasg

그 다음 장고 INSTALLED_APP에 다음 부분을 추가한다.

INSTALLED_APPS = [
   'drf_yasg',
]

프로젝트 내의 settings.py 에 아래와 같이 입력해준다.
(Django에서 이제는 url이 아닌 path를 지원하지만 drf-yasg 공식문서에는 url을 사용해서 url을 Import 해주었습니다)

from django.conf.urls import url
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="Snippets API",
      default_version='v1',
      description="Test description",
      terms_of_service="https://www.google.com/policies/terms/",
      contact=openapi.Contact(email="contact@snippets.local"),
      license=openapi.License(name="BSD License"),
   ),
   public=True,
   permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
   url(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
   url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
   url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
   ...
]

공식 문서에 따르면 다음과 같이 총 4개의 엔드포인트가 생성된다.

  • A JSON view of your API specification at /swagger.json
  • A YAML view of your API specification at /swagger.yaml
  • A swagger-ui view of your API specification at /swagger/
  • A ReDoc view of your API specification at /redoc/

생성된 API 문서 확인

위처럼 설정해줬다면 서버를 띄운 다음 바로 API 문서를 확인할 수 있다.

다음은 127.0.0.1:8000/swagger 로 접속한 결과물이다.

다음은 127.0.0.1:8000/redoc 으로 접속한 결과물이다.

그 외 127.0.0.1:8000/swagger.json 으로 접속한다면 json 파일을 웹 상에서 볼 수 있게 되고,
127.0.0.1:8000/swagger.yaml 으로 접속하면 yaml 파일이 다운로드 된다.

마무으리

간단한 프로젝트를 진행할 때는 협업하는 동료랑 상시 붙어있기 때문에 굳이 API 문서화를 할 필요 있을까라는 생각도 있었는데 (아, 물론 swagger 사용하는 법 조차 몰랐지만....) 저렇게 깔끔히 자동화되서 정리된 모습을 보니 실무에서 협업하기에는 너무 유용히 쓰이겠구나라는 생각이 들었다!

profile
Back-end Developer 🙇‍♂️ 💻 🙆‍♂️

2개의 댓글

comment-user-thumbnail
4일 전

이런게 있는지도 몰랐네요. 감사합니다. 그리고 면접에서 좋은 결과 있으시길 바래요.

1개의 답글