프로젝트 지식(5) - Swagger 사용법

학습동기

프로젝트를 진행하면서 프론트에게 API 명세서를 어떻게 하면 깔끔하게 전달해 줄 수 있을까 계속해서 고민을 했다. 다양한 방법이 있었는데, 그 중에서 가장 많이 쓰이는 Swagger 라이브러리를 알아보려 한다.

Swagger

간단하게 Swagger 알아보기

API 명세서를 자동으로 작성해주는 툴이다. Django 같은 경우 pip install drf-yasg를 통해 다운을 할 수 있다.

Swagger 기본 설정

프로젝트 폴더의 urls.py에 아래의 코드를 추가한다.

from drf_yasg import openapi
from drf_yasg.views import get_schema_view

schema_view = get_schema_view(
   openapi.Info(
      title="Snippets API", # API 문서 제목
      default_version='v1', # API 문서 버전
      description="Test description", # API 문서에 대한 간단한 설명
      terms_of_service="https://www.google.com/policies/terms/", # API 서비스 약관
      contact=openapi.Contact(email="contact@snippets.local"), # API 개발자 이메일
      license=openapi.License(name="BSD License"), # 라이센스
   ),
   public=True,
   permission_classes=[permissions.AllowAny],
)

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

Swagger 주석

간단한 API 설명을 쓰고 싶다면 “”” “”” 안에 기입하면 된다.

class ProfileDetail(GenericAPIView):
    """
        개인 프로필
        ---
        # 내용
            - user
            - user_pk
            - nickname
            - job
            - developer_level
            - designer_and_pm_level
            - image
            - mymail
            - myinfo
            - mygit
            - stacks 
            - portfolio
    """
    serializer_class = ProfileSerializer
    ...

Swagger와 View

drf-yasg에서는 serializer_classes로 API가 자동으로 생성된다. 따라서 그냥 View를 상속하면 swagger가 적용이 되지 않는다. 또한 APIView는 serializer_classes가 없기 때문에 swagger_auto_schema를 데코레이터로 사용하거나 GenericAPIView를 사용해야 한다.

swagger_auto_schema

API 문서가 자동화되기는 하지만 내가 원하는 request나 response가 제대로 나오지 않아 계속 고민했다. 계속 서치해본 결과 이를 해결하기 위해서는 swagger_auto_schema를 데코레이터로 사용해야 한다는 결론이 나왔다.

class google_callback(APIView):

    @swagger_auto_schema(
        operation_description="구글 소셜 로그인", 
        request_body=GoogleCallbackSerializer,
        responses={
            status.HTTP_201_CREATED: openapi.Response(
                description="Login Response",
                schema=RegisterSerializer
            )
        }
    )
    def post(self, request):
      ...

우선은 기본적인 기능만 구현을 해보았는데 swagger_auto_schema의 파라미터는 이것보다 훨씬 많다. 다음에 필요할 때 공식문서를 보고 한 번 해봐야겠다.

중요한 것만 정리를 좀 해본다면 query_serializer는 쿼리 파라미터를 설정할 수 있게 해주고, manual_parameters는 data 파라미터를 하나하나 설정할 수 있게 해준다.