Merge pull request #68 from Leets-Official/Refactor-#63-스웨거-컨트롤러마다-설명-추가

Refactor #63 스웨거 컨트롤러마다 설명 추가
Leets-Official · Oct 29, 2024 · af8763b · af8763b
2 parents bf46e00 + 89e71f6
commit af8763b
Show file tree

Hide file tree

Showing 19 changed files with 107 additions and 2 deletions.
diff --git a/src/main/java/leets/weeth/domain/account/presentation/AccountAdminController.java b/src/main/java/leets/weeth/domain/account/presentation/AccountAdminController.java
@@ -2,6 +2,8 @@
 
 import static leets.weeth.domain.account.presentation.ResponseMessage.ACCOUNT_SAVE_SUCCESS;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import leets.weeth.domain.account.application.dto.AccountDTO;
 import leets.weeth.domain.account.application.usecase.AccountUseCase;
@@ -12,6 +14,7 @@
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "AccountAdminController", description = "회비 관련 어드민 컨트롤러")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/admin/account")
@@ -20,6 +23,7 @@ public class AccountAdminController {
     private final AccountUseCase accountUseCase;
 
     @PostMapping
+    @Operation(summary="회비 총 금액 기입")
     public CommonResponse<Void> save(@RequestBody @Valid AccountDTO.Save dto) {
         accountUseCase.save(dto);
         return CommonResponse.createSuccess(ACCOUNT_SAVE_SUCCESS.getMessage());

diff --git a/src/main/java/leets/weeth/domain/account/presentation/AccountController.java b/src/main/java/leets/weeth/domain/account/presentation/AccountController.java
@@ -2,6 +2,8 @@
 
 import static leets.weeth.domain.account.presentation.ResponseMessage.ACCOUNT_FIND_SUCCESS;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import leets.weeth.domain.account.application.dto.AccountDTO;
 import leets.weeth.domain.account.application.usecase.AccountUseCase;
 import leets.weeth.global.common.response.CommonResponse;
@@ -10,7 +12,7 @@
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
-
+@Tag(name = "AccountController", description = "회비 관련 컨트롤러")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/account")
@@ -19,6 +21,7 @@ public class AccountController {
     private final AccountUseCase accountUseCase;
 
     @GetMapping("/{cardinal}")
+    @Operation(summary="회비 내역 조회")
     public CommonResponse<AccountDTO.Response> find(@PathVariable Integer cardinal) {
         return CommonResponse.createSuccess(ACCOUNT_FIND_SUCCESS.getMessage(),accountUseCase.find(cardinal));
     }

diff --git a/src/main/java/leets/weeth/domain/account/presentation/ReceiptAdminController.java b/src/main/java/leets/weeth/domain/account/presentation/ReceiptAdminController.java
@@ -3,6 +3,8 @@
 import static leets.weeth.domain.account.presentation.ResponseMessage.RECEIPT_DELETE_SUCCESS;
 import static leets.weeth.domain.account.presentation.ResponseMessage.RECEIPT_SAVE_SUCCESS;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import leets.weeth.domain.account.application.dto.ReceiptDTO;
 import leets.weeth.domain.account.application.usecase.ReceiptUseCase;
@@ -14,6 +16,7 @@
 
 import java.util.List;
 
+@Tag(name = "ReceiptAdminController", description = "회비 내역 관련 어드민 컨트롤러")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/admin/receipts")
@@ -22,12 +25,14 @@ public class ReceiptAdminController {
     private final ReceiptUseCase receiptUseCase;
 
     @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(summary="회비 사용 내역 기입")
     public CommonResponse<Void> save(@RequestPart @Valid ReceiptDTO.Save dto, @RequestPart(required = false) List<MultipartFile> images) {
         receiptUseCase.save(dto, images);
         return CommonResponse.createSuccess(RECEIPT_SAVE_SUCCESS.getMessage());
     }
 
     @DeleteMapping("/{receiptId}")
+    @Operation(summary="회비 사용 내역 취소")
     public CommonResponse<Void> delete(@PathVariable Long receiptId) {
         receiptUseCase.delete(receiptId);
         return CommonResponse.createSuccess(RECEIPT_DELETE_SUCCESS.getMessage());

diff --git a/src/main/java/leets/weeth/domain/attendance/presentation/AttendanceAdminController.java b/src/main/java/leets/weeth/domain/attendance/presentation/AttendanceAdminController.java
@@ -2,6 +2,8 @@
 
 import static leets.weeth.domain.attendance.presentation.ResponseMessage.ATTENDANCE_CLOSE_SUCCESS;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import leets.weeth.domain.attendance.application.usecase.AttendanceUseCase;
 import leets.weeth.global.common.response.CommonResponse;
 import lombok.RequiredArgsConstructor;
@@ -12,6 +14,7 @@
 
 import java.time.LocalDate;
 
+@Tag(name = "AttendanceAdminController", description = "출석 관련 어드민 컨트롤러")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/admin/attendances")
@@ -20,6 +23,7 @@ public class AttendanceAdminController {
     private final AttendanceUseCase attendanceUseCase;
 
     @PatchMapping
+    @Operation(summary="출석 마감")
     public CommonResponse<Void> close(@RequestParam LocalDate now, @RequestParam Integer cardinal) {
         attendanceUseCase.close(now, cardinal);
         return CommonResponse.createSuccess(ATTENDANCE_CLOSE_SUCCESS.getMessage());

diff --git a/src/main/java/leets/weeth/domain/attendance/presentation/AttendanceController.java b/src/main/java/leets/weeth/domain/attendance/presentation/AttendanceController.java
@@ -1,6 +1,8 @@
 package leets.weeth.domain.attendance.presentation;
 
+import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import leets.weeth.domain.attendance.application.dto.AttendanceDTO;
 import leets.weeth.domain.attendance.application.usecase.AttendanceUseCase;
 import leets.weeth.global.auth.annotation.CurrentUser;
@@ -14,6 +16,7 @@
 import static leets.weeth.domain.attendance.presentation.ResponseMessage.ATTENDANCE_FIND_ALL_SUCCESS;
 import static leets.weeth.domain.attendance.presentation.ResponseMessage.ATTENDANCE_FIND_SUCCESS;
 
+@Tag(name = "AttendanceController", description = "출석 관련 컨트롤러")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/attendances")
@@ -22,17 +25,20 @@ public class AttendanceController {
     private final AttendanceUseCase attendanceUseCase;
 
     @PatchMapping
+    @Operation(summary="출석체크")
     public CommonResponse<Void> checkIn(@Parameter(hidden = true) @CurrentUser Long userId, @RequestBody AttendanceDTO.CheckIn checkIn) throws AttendanceCodeMismatchException {
         attendanceUseCase.checkIn(userId, checkIn.code());
         return CommonResponse.createSuccess(ATTENDANCE_CHECKIN_SUCCESS.getMessage());
     }
 
     @GetMapping
+    @Operation(summary="출석 메인페이지")
     public CommonResponse<Main> find(@Parameter(hidden = true) @CurrentUser Long userId) {
         return CommonResponse.createSuccess(ATTENDANCE_FIND_SUCCESS.getMessage(), attendanceUseCase.find(userId));
     }
 
     @GetMapping("/detail")
+    @Operation(summary="출석 내역 상세조회")
     public CommonResponse<Detail> findAll(@Parameter(hidden = true) @CurrentUser Long userId) {
         return CommonResponse.createSuccess(ATTENDANCE_FIND_ALL_SUCCESS.getMessage(), attendanceUseCase.findAll(userId));
     }

diff --git a/src/main/java/leets/weeth/domain/board/presentation/NoticeAdminController.java b/src/main/java/leets/weeth/domain/board/presentation/NoticeAdminController.java
@@ -1,6 +1,8 @@
 package leets.weeth.domain.board.presentation;
 
+import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import leets.weeth.domain.board.application.dto.NoticeDTO;
 import leets.weeth.domain.board.application.usecase.NoticeUsecase;
@@ -16,6 +18,7 @@
 
 import static leets.weeth.domain.board.presentation.ResponseMessage.*;
 
+@Tag(name = "NoticeAdminController", description = "공지사항 관련 어드민 컨트롤러")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/admin/notices")
@@ -24,6 +27,7 @@ public class NoticeAdminController {
     private final NoticeUsecase noticeUsecase;
 
     @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(summary="공지사항 생성")
     public CommonResponse<String> save(@RequestPart @Valid NoticeDTO.Save dto,
                                        @RequestPart(value = "files", required = false) List<MultipartFile> files,
                                        @Parameter(hidden = true) @CurrentUser Long userId) {
@@ -32,6 +36,7 @@ public CommonResponse<String> save(@RequestPart @Valid NoticeDTO.Save dto,
     }
 
     @PatchMapping(value = "/{noticeId}", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(summary="특정 공지사항 수정")
     public CommonResponse<String> update(@PathVariable Long noticeId,
                                          @RequestPart @Valid NoticeDTO.Update dto,
                                          @RequestPart(value = "files", required = false) List<MultipartFile> files,
@@ -41,6 +46,7 @@ public CommonResponse<String> update(@PathVariable Long noticeId,
     }
 
     @DeleteMapping("/{noticeId}")
+    @Operation(summary="특정 공지사항 삭제")
     public CommonResponse<String> delete(@PathVariable Long noticeId, @Parameter(hidden = true) @CurrentUser Long userId) throws UserNotMatchException {
         noticeUsecase.delete(noticeId, userId);
         return CommonResponse.createSuccess(NOTICE_DELETED_SUCCESS.getMessage());

diff --git a/src/main/java/leets/weeth/domain/board/presentation/NoticeController.java b/src/main/java/leets/weeth/domain/board/presentation/NoticeController.java
@@ -4,6 +4,8 @@
 import static leets.weeth.domain.board.presentation.ResponseMessage.NOTICE_FIND_ALL_SUCCESS;
 import static leets.weeth.domain.board.presentation.ResponseMessage.NOTICE_FIND_BY_ID_SUCCESS;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import leets.weeth.domain.board.application.dto.NoticeDTO;
 import leets.weeth.domain.board.application.usecase.NoticeUsecase;
 import leets.weeth.global.common.response.CommonResponse;
@@ -12,6 +14,7 @@
 
 import java.util.List;
 
+@Tag(name = "NoticeController", description = "공지사항 관련 컨트롤러")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/notices")
@@ -20,11 +23,13 @@ public class NoticeController {
     private final NoticeUsecase noticeUsecase;
 
     @GetMapping
+    @Operation(summary="최근 공지사항 조회 및 입력된 개수 만큼 조회")
     public CommonResponse<List<NoticeDTO.ResponseAll>> findNotices(@RequestParam(required = false) Long noticeId, @RequestParam Integer count) {
         return CommonResponse.createSuccess(NOTICE_FIND_ALL_SUCCESS.getMessage(), noticeUsecase.findNotices(noticeId, count));
     }
 
     @GetMapping("/{noticeId}")
+    @Operation(summary="특정 공지사항 조회")
     public CommonResponse<NoticeDTO.Response> findNoticeById(@PathVariable Long noticeId) {
         return CommonResponse.createSuccess(NOTICE_FIND_BY_ID_SUCCESS.getMessage(), noticeUsecase.findNotice(noticeId));
     }

diff --git a/src/main/java/leets/weeth/domain/board/presentation/PostController.java b/src/main/java/leets/weeth/domain/board/presentation/PostController.java
@@ -1,6 +1,8 @@
 package leets.weeth.domain.board.presentation;
 
+import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import leets.weeth.domain.board.application.dto.PostDTO;
 import leets.weeth.domain.board.application.usecase.PostUsecase;
@@ -16,6 +18,7 @@
 
 import static leets.weeth.domain.board.presentation.ResponseMessage.*;
 
+@Tag(name = "PostController", description = "게시글 관련 컨트롤러")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/posts")
@@ -24,6 +27,7 @@ public class PostController {
     private final PostUsecase postUsecase;
 
     @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(summary="게시글 생성")
     public CommonResponse<String> save(@RequestPart @Valid PostDTO.Save dto,
                                        @RequestPart(value = "files", required = false) List<MultipartFile> files,
                                        @Parameter(hidden = true) @CurrentUser Long userId) {
@@ -32,16 +36,19 @@ public CommonResponse<String> save(@RequestPart @Valid PostDTO.Save dto,
     }
 
     @GetMapping
+    @Operation(summary="최근 게시글 조회 및 입력된 개수 만큼 조회")
     public CommonResponse<List<PostDTO.ResponseAll>> findPosts(@RequestParam(required = false) Long postId, @RequestParam Integer count) {
         return CommonResponse.createSuccess(POST_FIND_ALL_SUCCESS.getMessage(), postUsecase.findPosts(postId, count));
     }
 
     @GetMapping("/{postId}")
+    @Operation(summary="특정 게시글 조회")
     public CommonResponse<PostDTO.Response> findPost(@PathVariable Long postId) {
         return CommonResponse.createSuccess(POST_FIND_BY_ID_SUCCESS.getMessage(),postUsecase.findPost(postId));
     }
 
     @PatchMapping(value = "/{postId}", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(summary="특정 게시글 수정")
     public CommonResponse<String> update(@PathVariable Long postId,
                                          @RequestPart @Valid PostDTO.Update dto,
                                          @RequestPart(value = "files", required = false) List<MultipartFile> files,
@@ -51,6 +58,7 @@ public CommonResponse<String> update(@PathVariable Long postId,
     }
 
     @DeleteMapping("/{postId}")
+    @Operation(summary="특정 게시글 삭제")
     public CommonResponse<String> delete(@PathVariable Long postId, @Parameter(hidden = true) @CurrentUser Long userId) throws UserNotMatchException {
         postUsecase.delete(postId, userId);
         return CommonResponse.createSuccess(POST_DELETED_SUCCESS.getMessage());

diff --git a/src/main/java/leets/weeth/domain/comment/presentation/NoticeCommentController.java b/src/main/java/leets/weeth/domain/comment/presentation/NoticeCommentController.java
@@ -4,7 +4,9 @@
 import static leets.weeth.domain.comment.presentation.ResponseMessage.COMMENT_DELETED_SUCCESS;
 import static leets.weeth.domain.comment.presentation.ResponseMessage.COMMENT_UPDATED_SUCCESS;
 
+import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import leets.weeth.domain.comment.application.dto.CommentDTO;
 import leets.weeth.domain.comment.application.usecase.NoticeCommentUsecase;
@@ -14,7 +16,7 @@
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
-
+@Tag(name = "CommentController", description = "댓글 관련 컨트롤러")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/notices/{noticeId}/comments")
@@ -23,20 +25,23 @@ public class NoticeCommentController {
     private final NoticeCommentUsecase noticeCommentUsecase;
 
     @PostMapping
+    @Operation(summary="공지사항 댓글 작성")
     public CommonResponse<String> saveNoticeComment(@RequestBody @Valid CommentDTO.Save dto, @PathVariable Long noticeId,
                                                     @Parameter(hidden = true) @CurrentUser Long userId) {
         noticeCommentUsecase.saveNoticeComment(dto, noticeId, userId);
         return CommonResponse.createSuccess(COMMENT_CREATED_SUCCESS.getMessage());
     }
 
     @PatchMapping("{commentId}")
+    @Operation(summary="공지사항 댓글 수정")
     public CommonResponse<String> updateNoticeComment(@RequestBody @Valid CommentDTO.Update dto, @PathVariable Long noticeId,
                                                       @PathVariable Long commentId,@Parameter(hidden = true) @CurrentUser Long userId) throws UserNotMatchException {
         noticeCommentUsecase.updateNoticeComment(dto, noticeId, commentId, userId);
         return CommonResponse.createSuccess(COMMENT_UPDATED_SUCCESS.getMessage());
     }
 
     @DeleteMapping("{commentId}")
+    @Operation(summary="공지사항 댓글 삭제")
     public CommonResponse<String> deleteNoticeComment(@PathVariable Long commentId,
                                                       @Parameter(hidden = true) @CurrentUser Long userId) throws UserNotMatchException {
         noticeCommentUsecase.deleteNoticeComment(commentId, userId);

diff --git a/src/main/java/leets/weeth/domain/comment/presentation/PostCommentController.java b/src/main/java/leets/weeth/domain/comment/presentation/PostCommentController.java
@@ -4,7 +4,9 @@
 import static leets.weeth.domain.comment.presentation.ResponseMessage.POST_COMMENT_DELETED_SUCCESS;
 import static leets.weeth.domain.comment.presentation.ResponseMessage.POST_COMMENT_UPDATED_SUCCESS;
 
+import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import leets.weeth.domain.comment.application.dto.CommentDTO;
 import leets.weeth.domain.comment.application.usecase.PostCommentUsecase;
@@ -14,6 +16,7 @@
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
+@Tag(name = "CommentController", description = "댓글 관련 컨트롤러")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/posts/{postId}/comments")
@@ -22,20 +25,23 @@ public class PostCommentController {
     private final PostCommentUsecase postCommentUsecase;
 
     @PostMapping
+    @Operation(summary="게시글 댓글 작성")
     public CommonResponse<String> savePostComment(@RequestBody @Valid CommentDTO.Save dto, @PathVariable Long postId,
                                                   @Parameter(hidden = true) @CurrentUser Long userId) {
         postCommentUsecase.savePostComment(dto, postId, userId);
         return CommonResponse.createSuccess(POST_COMMENT_CREATED_SUCCESS.getMessage());
     }
 
     @PatchMapping("/{commentId}")
+    @Operation(summary="게시글 댓글 수정")
     public CommonResponse<String> updatePostComment(@RequestBody @Valid CommentDTO.Update dto, @PathVariable Long postId, @PathVariable Long commentId,
                                                     @Parameter(hidden = true) @CurrentUser Long userId) throws UserNotMatchException {
         postCommentUsecase.updatePostComment(dto, postId, commentId, userId);
         return CommonResponse.createSuccess(POST_COMMENT_UPDATED_SUCCESS.getMessage());
     }
 
     @DeleteMapping("{commentId}")
+    @Operation(summary="게시글 댓글 삭제")
     public CommonResponse<String> deletePostComment(@PathVariable Long commentId, @Parameter(hidden = true) @CurrentUser Long userId) throws UserNotMatchException {
         postCommentUsecase.deletePostComment(commentId, userId);
         return CommonResponse.createSuccess(POST_COMMENT_DELETED_SUCCESS.getMessage());

diff --git a/src/main/java/leets/weeth/domain/penalty/presentation/penaltyAdminController.java b/src/main/java/leets/weeth/domain/penalty/presentation/penaltyAdminController.java
@@ -4,6 +4,8 @@
 import static leets.weeth.domain.penalty.presentation.ResponseMessage.PENALTY_DELETE_SUCCESS;
 import static leets.weeth.domain.penalty.presentation.ResponseMessage.PENALTY_FIND_ALL_SUCCESS;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import leets.weeth.domain.penalty.application.dto.PenaltyDTO;
 import leets.weeth.domain.penalty.application.usecase.PenaltyUsecase;
 
@@ -13,6 +15,7 @@
 
 import java.util.List;
 
+@Tag(name = "penaltyAdminController", description = "패널티 관련 어드민 컨트롤러")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/admin/penalties")
@@ -21,17 +24,20 @@ public class penaltyAdminController {
     private final PenaltyUsecase penaltyUsecase;
 
     @PostMapping
+    @Operation(summary="전체 패널티 조회")
     public CommonResponse<String> assignPenalty(@RequestBody PenaltyDTO.Save dto){
         penaltyUsecase.save(dto);
         return CommonResponse.createSuccess(PENALTY_ASSIGN_SUCCESS.getMessage());
     }
 
     @GetMapping
+    @Operation(summary="패널티 부여")
     public CommonResponse<List<PenaltyDTO.Response>> findAll(){
         return CommonResponse.createSuccess(PENALTY_FIND_ALL_SUCCESS.getMessage(),penaltyUsecase.find());
     }
 
     @DeleteMapping
+    @Operation(summary="패널티 삭제")
     public CommonResponse<String> delete(@RequestParam Long penaltyId){
         penaltyUsecase.delete(penaltyId);
         return CommonResponse.createSuccess(PENALTY_DELETE_SUCCESS.getMessage());