SWAGGER/REDOC_api 문서 만들기

세팅

[settings.py]

INSTALLED_APPS = ["drf_yasg"]

• INSTALLED_APPS 에 drf_yasg 를 추가해준다.

[urls.py]

urlpatterns = [
    path(
        "swagger/",
        schema_view.with_ui("swagger", cache_timeout=0),
        name="schema-swagger-ui",
    ),
    path(
        "redoc/",
        schema_view.with_ui("redoc", cache_timeout=0),
        name="schema-redoc",
    ),
]

• urlpatterns 에 swagger과 redoc 둘다 혹은 둘중 하나의 경로를 추가해준다

• swagger 보여지는 화면 예시
  

• redoc 보여지는 화면 예시
  

[views.py]

from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi

• 문서를 사용하고자 하는 app의 views.py에 import 해준다.

GET

[views.py] ex

@swagger_auto_schema(
        operation_summary="피드 전체 조회",
        manual_parameters=[
            openapi.Parameter(
                "page",
                openapi.IN_QUERY,
                description="1 페이지당 24개의 데이터 (default = 1) \n - total_pages : 총 페이지수 \n - now_page : 현재 페이지 \n - count : 총 개수 \n - results : 순서",
                type=openapi.TYPE_INTEGER,
            ),
        ],
        responses={
            200: openapi.Response(
                description="Successful Response",
                schema=openapi.Schema(
                    type=openapi.TYPE_OBJECT,
                    properties={
                        "total_pages": openapi.Schema(
                            type=openapi.TYPE_INTEGER,
                            description="The total number of pages",
                        ),
                        "now_page": openapi.Schema(
                            type=openapi.TYPE_INTEGER,
                            description="The current page number",
                        ),
                        "count": openapi.Schema(
                            type=openapi.TYPE_INTEGER,
                            description="The total number of objects",
                        ),
                        "results": feed_schema,
                    },
                ),
            )
        },
    )

• operation_summary
  api문서를 설명하는 문장을 써준다
• manual_parameters
  파라미터로 받는 값이 있다면 받는 값(변수)과 변수에 대한 설명을 적어준다.
• responses
  입력에 대한 나올수 있는 결과를 적어준다.
• 보여지는 화면 예시
  

POST

[views.py] ex

@swagger_auto_schema(
        operation_summary="피드 생성",
        request_body=openapi.Schema(
            type=openapi.TYPE_OBJECT,
            required=["title", "category"],
            properties={
                "title": openapi.Schema(type=openapi.TYPE_STRING, description="타이틀"),
                "description": openapi.Schema(
                    type=openapi.TYPE_STRING, description="내용"
                ),
                "category": openapi.Schema(
                    type=openapi.TYPE_INTEGER, description="카테고리 pk"
                ),
                "image": openapi.Schema(
                    type=openapi.TYPE_STRING,
                    description="이미지 url, image:null -> 이미지 삭제",
                ),
            },
        ),
        responses={
            200: openapi.Response(
                description="OK", schema=serializers.FeedDetailSerializer
            ),
            400: openapi.Response(description="잘못된 형식의 데이터"),
            401: openapi.Response(description="비 로그인"),
            404: openapi.Response(description="카테고리 pk가 없거나 유효하지 않은 값"),
        },
    )

• operation_summary
  api 설명을 적어준다
• required
  필수로 post해야하는 변수를 적어준다
• properties
  post에 적는 모든 변수와 설명을 적어준다
• responses
  결과를 적어준다
• 보여지는 화면 예시
  

PUT

[views.py] ex

@swagger_auto_schema(
        operation_summary="피드 수정",
        request_body=openapi.Schema(
            type=openapi.TYPE_OBJECT,
            properties={
                "title": openapi.Schema(type=openapi.TYPE_STRING, description="타이틀"),
                "description": openapi.Schema(
                    type=openapi.TYPE_STRING, description="내용"
                ),
                "category": openapi.Schema(
                    type=openapi.TYPE_INTEGER, description="카테고리 pk"
                ),
                "image": openapi.Schema(
                    type=openapi.TYPE_STRING, description="이미지 url, 삭제하려면 Image:null"
                ),
            },
        ),
        responses={
            200: openapi.Response(
                description="Successful response",
                schema=serializers.FeedDetailSerializer(),
            ),
            400: "Bad Request",
            403: "PermissionDenied",
            404: "Not Found",
        },
    )

-post와 같다.

DELETE

[views.py] ex

    @swagger_auto_schema(
        operation_summary="피드 삭제",
        responses={
            204: openapi.Response(description="Successful response"),
            403: "PermissionDenied",
        },
    )