diff --git a/src/notice/swagger.py b/src/notice/swagger.py new file mode 100644 index 0000000..3743e08 --- /dev/null +++ b/src/notice/swagger.py @@ -0,0 +1,119 @@ +from drf_spectacular.utils import OpenApiExample, OpenApiParameter, OpenApiResponse + +from core.responses.serializer import ( + ErrorResponseSerializer, + ListSuccessResponseSerializer, + SuccessResponseSerializer, +) +from core.swagger import SwaggerSchema + + +class NoticeAPIDocs(SwaggerSchema): + sample_notice_detail = { + "id": 1, + "title": "공지 사항 제목 1", + "content": "
공지 사항 입니다.
", + "is_pinned": True, + "created_at": "2021-01-01 00:00:00", + "updated_at": "2021-01-01 00:00:00", + } + sample_notice_list = [ + { + "id": 2, + "title": "공지 사항 제목 2", + "is_pinned": True, + }, + { + "id": 1, + "title": "공지 사항 제목 1", + "is_pinned": True, + }, + ] + + @classmethod + def retrieve(cls): + responses = { + "성공": OpenApiResponse( + response=SuccessResponseSerializer, + description="단일 응답 성공", + examples=[ + OpenApiExample( + name="공지 사항 상세 조회", + value={ + "status": "SUCCESS", + "data": cls.sample_notice_detail, + }, + ), + ], + ), + "에러": OpenApiResponse( + response=ErrorResponseSerializer, + description="응답 에러", + examples=[ + OpenApiExample( + name="데이터 없음", + value={ + "status": "ERROR", + "error": {"code": "NOT_EXIST", "message": "데이터가 없습니다."}, + }, + ), + ], + ), + } + return cls.generate_schema( + operation_id="notice_retrieve", description="공지 사항 상세 조회", responses=responses + ) + + @classmethod + def list(cls): + parameters = [ + OpenApiParameter( + name="is_pinned", + type=bool, + location=OpenApiParameter.QUERY, + description="고정된 공지만 조회", + ), + ] + responses = { + "성공": OpenApiResponse( + response=ListSuccessResponseSerializer, + description="다중 응답 성공", + examples=[ + OpenApiExample( + name="공지 사항 목록 조회 (페이지네이션 있음)", + value={ + "status": "SUCCESS", + "data": cls.sample_notice_list, + "pagination": { + "count": 20, + "next": "http://localhost:8000/api/v1/notice/?page=2", + "previous": "http://localhost:8000/api/v1/notice/?page=1", + }, + }, + ), + OpenApiExample( + name="공지 사항 목록 조회 (데이터 있음)", + value={ + "status": "SUCCESS", + "data": cls.sample_notice_list, + "pagination": {"count": 1, "next": None, "previous": None}, + }, + ), + OpenApiExample( + name="공지 사항 목록 조회 (데이터 없음)", + value={ + "status": "SUCCESS", + "data": [], + "pagination": {"count": 0, "next": None, "previous": None}, + }, + ), + ], + ), + "에러": OpenApiResponse(response=ErrorResponseSerializer, description="응답 에러"), + } + return cls.generate_schema( + operation_id="notice_list", + description="공지 사항 목록 조회", + responses=responses, + parameters=parameters, + ) diff --git a/src/notice/views.py b/src/notice/views.py index 440e894..1b403dd 100644 --- a/src/notice/views.py +++ b/src/notice/views.py @@ -1,11 +1,14 @@ +from drf_spectacular.utils import extend_schema_view from rest_framework.viewsets import GenericViewSet from core.responses.base import BaseResponse from .models import Notice from .serializers import NoticeSerializer +from .swagger import NoticeAPIDocs +@extend_schema_view(list=NoticeAPIDocs.list(), retrieve=NoticeAPIDocs.retrieve()) class NoticeViewSet(GenericViewSet): serializer_class = NoticeSerializer queryset = Notice.objects.filter(is_deleted=False)