django에 swagger 만들기, drf-spectacular

class KakaoAuthorize(PublicView):
    @extend_schema(
        parameters=[
            OpenApiParameter(
                name="code",
                type=OpenApiTypes.STR,
                location=OpenApiParameter.QUERY,
                description="Authorization code",
                required=True,
            )
        ],
        responses={
            status.HTTP_200_OK: LoginTokenSerializer(),
            status.HTTP_400_BAD_REQUEST: BAD_REQUEST_RESPONSE
        },
    )
    def get(self, request, *args, **kwargs):

 

 

 

📕API 스펙 공유를 위한 swagger

개발자들에게 swagger는 아주 친숙한 이름이다. 프론트엔드와 백엔드 모두 자주 활용하는 기능인데, API 스펙에 대한 명세를 확인할 수 있는 '공유 문서'라고 생각하면 된다. 웹 브라우져를 이용해 GUI형태로 제공되기 때문에 보기 편하고, 실제로 API를 호출해 볼 수 있기도 하다. (보안 때문에 실제 운영 서버에서는 swagger로 호출을 막아놓기는 한다.)

 

예전에 장고 프로젝트를 진행할 때는 drf-yasg를 사용했었는데, 최근에 drf-spectacular라는게 더 잘 나가는 패키지인 것 같다. 지원하는 버전이 더 높은가 보다. drf-spectacular를 사용하면서 이것저것 세팅을 좀 해보면서 사용법을 정리해 본다.

 

swagger 실행 화면

 

 

⬇️ 설치하기

먼저 패키지를 설치해야한다. 

pip install drf-spectacular

 

현재기준 0.27.1버전이 최신버전인데, 계속해서 버전 업되고 있는 모양이다. 깃헙링크 : https://github.com/tfranzel/drf-spectacular

 

 

패키지를 설치하고 몇가지 세팅이 필요한데, 일단 settings.py에 아래와 같은 코드를 추가해야 한다.

 

# settings.py

INSTALLED_APPS = [
    ...
    'drf_spectacular',   # installed_app에 추가
    ...
]

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}



SPECTACULAR_SETTINGS = {
    # General schema metadata. Refer to spec for valid inputs
    # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#openapi-object
    'TITLE': 'drf-spectacular API Document',
    'DESCRIPTION': 'drf-specatular 를 사용해서 만든 API 문서입니다.',
    'SWAGGER_UI_SETTINGS': {
        'dom_id': '#swagger-ui',
        'layout': 'BaseLayout', 
        'deepLinking': True,  
        'displayOperationId': True,
        'filter': True,
    },
   
    'LICENSE': {
        'name': 'MIT License',
    },
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,

    'SWAGGER_UI_DIST': '//unpkg.com/swagger-ui-dist@3.38.0',
}

 

 

SPECTACULAR_SETTINGS가 실제로 swagger화면에 이것저것 옵션을 넣는 설정인데, 자세한 설정값들은 요기를 가면 확인할 수 있다.

 

이제 다음으로 urls.py를 수정하면 스웨거 화면을 띄울 수 있다.

 

# urls.py
from drf_spectacular.views import SpectacularJSONAPIView, SpectacularYAMLAPIView, SpectacularSwaggerView, \
    SpectacularRedocView

urlpatterns = [
    path("swagger.json/", SpectacularJSONAPIView.as_view(), name="schema-json"),
    path("swagger.yaml/", SpectacularYAMLAPIView.as_view(), name="swagger-yaml"),
    path("swagger/", SpectacularSwaggerView.as_view(url_name="schema-json"), name="swagger-ui", ),
    path("redoc/", SpectacularRedocView.as_view(url_name="schema-json"), name="redoc", ),
    ...
]

 

 

일반적인 url path는 ~/swagger 지만 json이나 yaml형태로 데이터를 받고 싶은 클라이언트가 있기 때문에 swagger.json, swagger.yaml도 추가했다. 

 

이제 django 프로젝트를 실행하면 swagger화면이 뜨는것을 확인할 수 있다!!

 

 

🧑‍💻 커스터마이징

 

위처럼 설치만 하고 swagger를 띄우면 단순히 API 리스트만 나오고 다른 정보들은 표기되지 않는다. 이런 것들까지 자동으로 찾아서 보여준다면 아주 좋겠지만, 각 API마다 request나 response type을 일일이 지정해 줘야 좀 더 swagger를 잘 활용할 수 있다. 

 

아래는 카카오 인증을 하는 API에 대해 parameter를 세팅한 예시이다.

 

 

class KakaoAuthorize(PublicView):
    @extend_schema(
        parameters=[
            OpenApiParameter(
                name="code",
                type=OpenApiTypes.STR,
                location=OpenApiParameter.QUERY,
                description="Authorization code",
                required=True,
            )
        ],
        responses={
            status.HTTP_200_OK: LoginTokenSerializer(),
            status.HTTP_400_BAD_REQUEST: BAD_REQUEST_RESPONSE
        },
    )
    def get(self, request, *args, **kwargs):
        ...

 

 

기본적으로 parameters, request, responses 3개만 잘 세팅하면 된다. parameters는 헤더나 path에 세팅되는 값, request는 body에 세팅되는 값, response는 응답값이다.

 

parameters같은 경우 OpenApiParameter를 사용해 표기할 수 있고, request와 response는 serializer로 표현할 수 있는데, serializer로 표현하면 어떤 타입의 field인지만 보여줄 수 있다. drf-spectacular에서 제공하는 OpenApiRequest와 OpenApiResponse를 활용하면 serializer정보 + 예제 요청/응답과 같은 추가적인 정보를 세팅할 수 있다.

 

위에 responses에서 200인경우는 LoginTokenSerializer라는 serializer정보를 내려주고, 400 응답일 경우 BAD_REQUEST_RESPONSE라는 OpenApiResponse 클래스를 내려주는데, 각 클래스 구현은 아래와 같다.

 

class LoginTokenSerializer(serializers.ModelSerializer):
    class Meta:
        model = LoginToken
        depth = 1
        fields = ['access_token', 'refresh_token', 'expires_in', 'refresh_token_expires_in', 'secret_key']



class BadRequestResponse(OpenApiResponse):
    def __init__(self):
        super().__init__(
            inline_serializer(
                name="BadRequest",
                fields={
                    "error_code": serializers.CharField(),
                    "message": serializers.CharField(),
                    "display_type": serializers.CharField(),
                },
                allow_null=True,
            ),
            description="Bad request",
            examples=[
                OpenApiExample(
                    name="Bad JSON passed in",
                    value={
                        "error_code": "notification",
                        "message": "",
                        "display_type": "event_type and event_parameters fields are required",
                    },
                    status_codes=["400"],
                ),
                OpenApiExample(
                    name="Not good JSON",
                    value={
                        "detail": "JSON parse error - Expecting ':' delimiter: line 2 column 17 (char 18)"
                    },
                    status_codes=["400"],
                ),
            ],
        )

 

 

위 코드가 swagger에서 표현되는 화면은 아래와 같다.

 

실제로 노출되는 화면

 

200이 serializer, 400이 OpenApiResponse를 사용한 항목이다. serializer의 경우 각 field와 type이 적혀있긴 하지만, 구체적으로 어떤 값이 나오는지는 확인할 수 없다. (사실 이 정도만 해도...)   400의 경우는 실제로 field에 어떤 값이 들어갈지 세팅할 수 있어서 개발할 때 더 효과적이다.

 

정말 완벽하게 swagger를 사용하기 위해서는 OpenApiResponse를 각 API마다 만들어주는게 좋겠지만, 대충 어느 type인지만 알아도 개발이 가능하기 때문에 고민해 볼 필요가 있다. 개발 팀의 커뮤니케이션 빈도가 높다면 굳이 swagger에 모든 정보를 노출하는 것보다는, 딱 필요정보만 보여주고 다른 건 다른 의사소통 채널을 통해 진행하는 게 더 좋을 수 있다. 반대로 회의 Cost가 높다고 생각한다면 (물리적인 위치가 멀어서 ?) 완벽한 Swagger문서를 공유하는 것이 더 바람직할 수 있다. 진리의 케바케

 

 

 

📝 마치며

 

이전에 사용했던 drf-yasg와 사용하는 방법에는 큰 차이가 없다. 하지만 OpenApi 3.0 스펙을 제공하는 것은 drf-spectacular만 제공하며, drf-yasg문서에는 drf-spectacular를 사용하라고 적혀있다 ㅎㅎ 

 

swagger를 사용하는 이유는 개발 편의이기 때문에, swagger를 사용하면서 개발일정이 길어진다거나 작업이 어려운 경우 사용하지 않는 게 바람직하다. 일을 위한 일을 하지 않는 것이 제일 좋다고 생각한다.

 

하지만 특정 클라이언트들은 swagger를 보고 자동으로 API 호출 코드를 생성하는 라이브러리를 사용하기도 한다. 따라서 꼭 필요하거나, 개발 생산성이 높아진다면 무조건 사용하는게 이득이라고 생각한다.