django drf-yasg API 문서 커스텀하기 (@swagger_auto_schema) (FBV)

앞서 해당 내용을 진행하기 위해선 drf-yasg가 install되어있어야한다.

함수형 뷰(FBV)를 기준으로 설명한 내용이다.

API 문서를 작성할때 부가적인 내용을 추가적으로 적지 않으면 어떠한 내용인지 잘 모르는 경우로 나타내어진다.

그렇기 때문에 각각 정리가 필요한데 작성법은 아래의 코드로 알아볼 수 있다.

@api_view(['POST'])
def index(request):
      """
      해당 내용의 주제

      ---
      ## 경로
      ## 파라미터 설명

              - id : user id (예시)
      """
      if request.method == 'POST':
          return Response()

단순하게 이렇게만 적어도 깔끔하게 나오는걸 확인할 수 있다.

그렇다면 HTTP METHOD가 두개 이상이라면 어떻게 표기하는가?

위 코드 처럼 표시한다면 GET, POST, PUT, DELETE가 다 같은 내용으로 통일 될것이다.

그러한 부분을 방지하기 위해 @swagger_auto_schema 을 사용 할 수 있는데 처음 사용해보는거라 애좀 먹었지만 사용방법을 알아냈다. (물론 이게 맞는 방법이란 생각은 안한다. 더 좋은 방법이 있을거라 생각한다.)

from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
        method='get',
      operation_summary='''해당 내용의 주제''',
      operation_description=
      '''
      ## 경로
      .. 등등 내용 입력
      '''
)
@swagger_auto_schema(
        method='post',
      operation_summary='''해당 내용의 주제''',
      operation_description=
      '''
      ## 경로
      ## 파라미터 설명
      '''
)
@api_view(['GET','POST'])
def index(reqeust):
      if request.method == 'GET':
          return Response()
    elif request.method == 'POST':
          return Response()

위에 보면 http method를 사용한 만큼 swagger_auto_schema를 사용할 수 있다.

일단 기본적으로 이렇게 쓰이고 좀 더 파고 들자면

request_body과 response의 내용을 사용자가 원하는대로 설정가능하다.

여기서 request_body는 POST요청이나 PUT요청을 할때 값을 보낼때 참고 할 수 있는 내용을 의미 한다.

response는 요청받고 응답으로 내어놓는 값을 참고 할 수 있게 정리한 내용을 의미한다.

@swagger_auto_schema(
        method='post',
      ...
      request_body=openapi.Schema(
            '해당 내용의 titile',
          type=openapi.TYPE_OBJECT,
          properties={
              'fullname': openapi.Schema('사용자 이름', type=openapi.TYPE_STRING),
            'nickname': openapi.Schema('사용자 닉네임', type=openpi.TYPE_STRING),
              ...
        },
          required=['fullname']  # 필수값을 지정 할 Schema를 입력해주면 된다.
    ),
      responses={
          200: openapi.Schema(
                type=openapi.TYPE_OBJECT,
              properties={
                  'id': openapi.Schema('사용자 id', type=openapi.TYPE_INTEGER),
                  'fullname': openapi.Schema('사용자 이름', type=openapi.TYPE_STRING),
                    'nickname': openapi.Schema('사용자 닉네임', type=openpi.TYPE_STRING),
                  ...
            }
        )
    }
)

일단 뭔지 잘 모르겠다면 이렇게 입력하고 API 문서를 직접 보며 이해해볼 수 있다.

responses에는 200 이후에 serializer를 넣어도된다. 그러면 자동으로 생성이 된다.

path parameter를 추가 해주고 싶다면 아래코드 처럼 하면 된다.

@swagger_auto_schema(
        method='get',
      ...
      manual_parameters=[
          openapi.Parameter(
            'authorication',
            openapi.IN_PATH,
            type=openapi.TYPE_STRING,
            description='API 키: 헤더에 Authorization Bearer {API Key} 형태로 전달'
        )
    ]
)