본문 바로가기
카테고리 없음

Swagger와 drf-yasg (API 문서 자동화 도구)

by yororing 2024. 3. 26.

00 API 문서화 개요

1. API 문서화의 중요성

1) 배경

  • 구두/수기로 작성한 문서로 주고 받기에는 불편함이 많음
  • 개발 작업 특성상 서로간 공유해야하는 수많은 내부 요소들이 있고, 이 중 하나라도 누락이 되면 정상 기능을 방해하는 오류 발생
  • 이런 불편함을 해소하고자 API를 자동으로 문서화 할 수 있는 방안 고안
  • API 문서화 도구: 서로의 통신 내용을 직관적으로 파악할 수 있게끔하는 웹 개발자의 필수 보조 작업물

2) API 문서화란

  • 백엔드가 작성한 각각의 API 기능을 문제없이 사용하기 위해서, 개발자 간 어떠한 구성 요소를 주고 받아야하는지 분명/뚜렷하게 정리하는 작업

2. API 문서화의 장점

1) 개인의 장점

  • 자신의 작업물을 다른 사람과 효율적으로 공유 가능
  • API 기능 정의서에는 목적, 의도, 엔드포인드, API별 필수 인자 등에 대한 세부 정보가, 개발자는 물론 일반 사용자 까지 모두 이해하기 쉬운 형식으로 구조화되어있음
  • 기능 설명서는 개발자 개인이 직접적으로 타인과 소통해야만 하는 빈도를 확연히 줄여줄 수 있고, 그 결과 일의 능률 높임
  • 사용자로 하여금 다양한 요청-응답 방식을 더 잘 이해할 수 있게 관련 예제나 영상도 같이 업로드 하기도 하는데, 이는 초기에 소비한 시간 이후 비용은 최소화됨을 의미함

2) 기업의 장점

  • 새 사용자들이 익숙해지기까지 소요되는 평균 시간을 줄여줌. 복잡한 API 구조의 서비스를 제공하는 다양한 기업들이, 더 많은 사용자를 유치할 수 있는 전략으로 사용됨
  • 사용자에게 API를 구현하기 전 미리 시험해볼 수 있는 기능을 선제공할 수 도 있으며, 직접 API를 사용하는 팀의 경우, 해당 기업에 궁금한 점들을 직접 질문하기 위해 연락하는 시간과 빈도를 줄여줄 수 있음
  • API 문서화는 우수한 상태의 제품 유지 관리로 이어짐. 개발부서 모든 팀이 실시간으로 반영되는 리소스, 방법, 관련 요청 - 응답에 대한 세부 정보를 공유한 상태라고 가정한다면, 관련 API에 대한 유지,관리,업데이트 등을 더 효과적으로 수행할 수 있게 됨

3. API 문서화의 필수 요소

  • 해당 API의 사용 예시
  • URI (엔드포인드)
  • 샘플 REQUEST 양식
  • Request parameter
  • Response parameter
  • 에러 핸들링 정보
  • Etc

01 Swagger와 drf-yasg의 정의

1. Swagger

  • API 서버를 자동으로 문서화 시켜주는 도구 (API 문서 생성 및 시각화)
  • API의 엔드포인트, 매개변수, 응답 형식 등을 문서화 가능케 함

2. drf-yasg

  • 'Django REST Framework Yet Another Swagger Generator'의 약자
  • DRF로 정의한 API를 문서화 하는 라이브러리 (Django에서 제공)
  • 특징: Swagger의 부족한 부분을 채워줌
    • nested serializer와 schema 대응 
    • response schema 및 field-level description 가능
    • swagger-spec-validator 혹은 flex로 schema validation 가능 
    • Versioning 가능 
    • Swagger-UI / Redoc 활용 가능

01 Swagger와 drf-yasg 사용하기

1) drf_yasg.openapi 모듈

from drf_yasg import openapi
  • drf-yasg의 openapi는 Swagger (Openapi)의 Specification 또는 Schema를 프로그래밍 방식으로 작성 및 정의함
  • 사용 예시:
    • openapi.Parameter 클래스를 사용하여 API 엔드포인트에 필요한 매개변수 정의 
      • # API 매개변수(파라미터)를 정의
request = openapi.Parameter('user_account', openapi.IN_QUERY,
                            description = "None일 경우 전체검색",
                            type=openapi.TYPE_STRING)
request_useraccount = openapi.Parameter('user_account', openapi.IN_QUERY, required = True,
                            description = "",                   
                            type = openapi.TYPE_STRING)
    • openapi.Response를 사용하여 API의 응답 형식 정의 
      • @swagger_auto_schema(
    operation_id = 'Session list',
    operation_description = '이전에 생성된 세션 목록을 제공하는 API',
    manual_parameters = [request],
    responses = {
        200: openapi.Response('Response', serializer.SessionsSerializer),
        }
    )

2) @swagger_auto_schema 데코레이터

from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    operation_id = 'Session list',
    operation_description = '이전에 생성된 세션 목록을 제공하는 API',
    manual_parameters = [request],
    responses = {
        200: openapi.Response('Response', serializer.SessionsSerializer),
        }
    )
  • APIView의 메서드(GET, POST, PUT, DELETE 등) 위에 사용, 해당 메서드에 대한 Swagger 스펙(OpenAPI Specification)을 자동으로 생성하는 데코레이터
  • swagger_auto_schema 사용하여 API의 동작 설명, 문서화 가능
    • 예: API 엔드포인트에 대한 작업 ID, 작업 설명, 매개변수, 응답 등을 정의 가능
    • 이 정보는 drf-yasg를 통해 API 문서로 자동 변환되어 사용자에게 제공됨
 

참조

  1. https://drf-yasg.readthedocs.io/en/stable/
  2. https://medium.com/towncompany-engineering/친절하게-django-rest-framework-api-문서-자동화하기-drf-yasg-c835269714fc%EF%BB%BF
  3. https://velog.io/@lu_at_log/drf-yasg-and-swagger  
  4. https://pabeba.tistory.com/38
  5. https://www.django-rest-framework.org/topics/documenting-your-api/
  6.  

티스토리툴바