Merge pull request #48 from Team-Shaka/docs/47

Docs/47 - API 문서화 작업 및 이미지 관련 동작 최적화
Team-Shaka · Feb 24, 2024 · 42db791 · 42db791
2 parents e459256 + 4bdebbb
commit 42db791
Show file tree

Hide file tree

Showing 18 changed files with 71 additions and 15 deletions.
diff --git a/src/main/java/org/example/tree/domain/comment/controller/CommentController.java b/src/main/java/org/example/tree/domain/comment/controller/CommentController.java
@@ -1,5 +1,6 @@
 package org.example.tree.domain.comment.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
 import lombok.RequiredArgsConstructor;
 import org.example.tree.domain.comment.dto.CommentRequestDTO;
 import org.example.tree.domain.comment.dto.CommentResponseDTO;
@@ -15,6 +16,7 @@ public class CommentController {
     private final CommentService commentService;
 
     @PostMapping("/trees/{treeId}/feed/posts/{postId}/comments")
+    @Operation(summary = "댓글 작성", description = "특정 게시글에 댓글 작성합니다.")
     public ApiResponse createComment(
             @PathVariable final Long treeId,
             @PathVariable final Long postId,
@@ -28,6 +30,7 @@ public ApiResponse createComment(
     }
 
     @GetMapping("/trees/{treeId}/feed/posts/{postId}/comments")
+    @Operation(summary = "댓글 조회", description = "Reaction과 댓글에 달린 답글도 같이 출력됩니다.")
     public ApiResponse<List<CommentResponseDTO.getComment>> getComments(
             @PathVariable final Long treeId,
             @PathVariable final Long postId,
@@ -38,6 +41,7 @@ public ApiResponse<List<CommentResponseDTO.getComment>> getComments(
     }
 
     @PatchMapping("/trees/{treeId}/feed/posts/{postId}/comments/{commentId}")
+    @Operation(summary = "댓글 수정", description = "댓글을 수정합니다.")
     public ApiResponse updateComment(
             @PathVariable final Long treeId,
             @PathVariable final Long postId,
@@ -51,6 +55,7 @@ public ApiResponse updateComment(
     }
 
     @DeleteMapping("/trees/{treeId}/feed/posts/{postId}/comments/{commentId}")
+    @Operation(summary = "댓글 삭제", description = "댓글을 삭제합니다.")
     public ApiResponse deleteComment(
             @PathVariable final Long treeId,
             @PathVariable final Long postId,

diff --git a/src/main/java/org/example/tree/domain/comment/controller/ReplyController.java b/src/main/java/org/example/tree/domain/comment/controller/ReplyController.java
@@ -1,5 +1,6 @@
 package org.example.tree.domain.comment.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
 import lombok.RequiredArgsConstructor;
 import org.example.tree.domain.comment.dto.ReplyRequestDTO;
 import org.example.tree.domain.comment.service.ReplyService;
@@ -12,6 +13,7 @@ public class ReplyController {
     private final ReplyService replyService;
 
     @PostMapping("/trees/{treeId}/feed/comments/{commentId}/reply")
+    @Operation(summary = "답글 작성", description = "특정 댓글에 답글을 작성합니다.")
     public ApiResponse createReply(
             @PathVariable final Long treeId,
             @PathVariable final Long commentId,
@@ -24,6 +26,7 @@ public ApiResponse createReply(
     }
 
     @PatchMapping("/trees/{treeId}/feed/comments/{commentId}/reply/{replyId}")
+    @Operation(summary = "답글 수정", description = "답글을 수정합니다.")
     public ApiResponse updateReply(
             @PathVariable final Long treeId,
             @PathVariable final Long commentId,
@@ -37,6 +40,7 @@ public ApiResponse updateReply(
     }
 
     @DeleteMapping("/trees/{treeId}/feed/comments/{commentId}/reply/{replyId}")
+    @Operation(summary = "답글 삭제", description = "답글을 삭제합니다.")
     public ApiResponse deleteReply(
             @PathVariable final Long treeId,
             @PathVariable final Long commentId,

diff --git a/src/main/java/org/example/tree/domain/comment/converter/CommentConverter.java b/src/main/java/org/example/tree/domain/comment/converter/CommentConverter.java
@@ -25,7 +25,8 @@ public Comment toComment(String content, Profile profile, Post post) {
     public CommentResponseDTO.getComment toGetComment(Comment comment, List<ReactionResponseDTO.getReaction> reactions, List<ReplyResponseDTO.getReply> replies) {
         return CommentResponseDTO.getComment.builder()
                 .commentId(comment.getId())
-                .memberName(comment.getProfile().getMemberName())
+                .authorId(comment.getProfile().getId())
+                .authorName(comment.getProfile().getMemberName())
                 .content(comment.getContent())
                 .reactions(reactions)
                 .createdAt(comment.getCreatedAt())

diff --git a/src/main/java/org/example/tree/domain/comment/converter/ReplyConverter.java b/src/main/java/org/example/tree/domain/comment/converter/ReplyConverter.java
@@ -24,7 +24,8 @@ public Reply toReply(String content, Profile profile, Comment comment) {
     public ReplyResponseDTO.getReply toGetReply(Reply reply, List<ReactionResponseDTO.getReaction> reactions) {
         return ReplyResponseDTO.getReply.builder()
                 .replyId(reply.getId())
-                .memberName(reply.getProfile().getMemberName())
+                .authorId(reply.getProfile().getId())
+                .authorName(reply.getProfile().getMemberName())
                 .content(reply.getContent())
                 .reactions(reactions)
                 .createdAt(reply.getCreatedAt())

diff --git a/src/main/java/org/example/tree/domain/comment/dto/CommentResponseDTO.java b/src/main/java/org/example/tree/domain/comment/dto/CommentResponseDTO.java
@@ -16,7 +16,8 @@ public class CommentResponseDTO {
     @AllArgsConstructor
     public static class getComment {
         private Long commentId;
-        private String memberName;
+        private Long authorId;
+        private String authorName;
         private String content;
         private List<ReactionResponseDTO.getReaction> reactions;
         private LocalDateTime createdAt;

diff --git a/src/main/java/org/example/tree/domain/comment/dto/ReplyResponseDTO.java b/src/main/java/org/example/tree/domain/comment/dto/ReplyResponseDTO.java
@@ -15,7 +15,8 @@ public class ReplyResponseDTO {
     @AllArgsConstructor
     public static class getReply {
         private Long replyId;
-        private String memberName;
+        private Long authorId;
+        private String authorName;
         private String content;
         private List<ReactionResponseDTO.getReaction> reactions;
         private LocalDateTime createdAt;

diff --git a/src/main/java/org/example/tree/domain/invitation/controller/InvitationController.java b/src/main/java/org/example/tree/domain/invitation/controller/InvitationController.java
@@ -1,5 +1,6 @@
 package org.example.tree.domain.invitation.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
 import lombok.RequiredArgsConstructor;
 import org.example.tree.domain.invitation.dto.InvitationRequestDTO;
 import org.example.tree.domain.invitation.dto.InvitationResponseDTO;
@@ -15,13 +16,15 @@ public class InvitationController {
     private final InvitationService invitationService;
 
     @PostMapping("/users/invitation")
+    @Operation(summary = "신규회원 초대", description = "서비스에 미가입된 사용자를 초대합니다.")
     public ApiResponse<InvitationResponseDTO.sendInvitation> sendInvitation(
             @RequestBody final InvitationRequestDTO.sendInvitation request
     ) {
         return ApiResponse.onSuccess(invitationService.inviteUser(request));
     }
 
     @PostMapping("/trees/members/invitation")
+    @Operation(summary = "회원 초대", description = "서비스에 가입되어 있는 멤버를 다른 트리하우스에 초대합니다.")
     public ApiResponse inviteMember(
             @RequestBody final InvitationRequestDTO.inviteMember request
     ) {
@@ -30,20 +33,23 @@ public ApiResponse inviteMember(
     }
 
     @PostMapping("/trees/members/invitation/accept")
+    @Operation(summary = "초대 수락", description = "받은 초대를 수락합니다.")
     public ApiResponse<InvitationResponseDTO.acceptInvitation> acceptInvitation(
             @RequestBody final InvitationRequestDTO.acceptInvitation request
     ) {
         return ApiResponse.onSuccess(invitationService.acceptInvitation(request));
     }
 
     @PostMapping("/trees/members/invitation/reject")
+    @Operation(summary = "초대 거절", description = "받은 초대를 거절합니다.")
     public ApiResponse<InvitationResponseDTO.rejectInvitation> rejectInvitation(
             @RequestBody final InvitationRequestDTO.rejectInvitation request
     ) {
         return ApiResponse.onSuccess(invitationService.rejectInvitation(request));
     }
 
     @GetMapping("/users/invitation")
+    @Operation(summary = "초대장 조회", description = "내가 받은 초대장을 조회합니다.")
     public ApiResponse<List<InvitationResponseDTO.getInvitation>> getInvitation(
             @RequestHeader("Authorization") final String header
     ) {
@@ -52,6 +58,7 @@ public ApiResponse<List<InvitationResponseDTO.getInvitation>> getInvitation(
     }
 
     @GetMapping("/users/availableInvitation")
+    @Operation(summary = "가용 초대장 조회", description = "내가 보낼 수 있는 초대장 개수를 조회합니다.")
     public ApiResponse<InvitationResponseDTO.getAvailableInvitation> getAvailableInvitation(
             @RequestHeader("Authorization") final String header
     ) {

diff --git a/src/main/java/org/example/tree/domain/member/controller/MemberController.java b/src/main/java/org/example/tree/domain/member/controller/MemberController.java
@@ -1,5 +1,6 @@
 package org.example.tree.domain.member.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
 import lombok.RequiredArgsConstructor;
 import org.example.tree.domain.member.dto.MemberRequestDTO;
 import org.example.tree.domain.member.dto.MemberResponseDTO;
@@ -13,12 +14,14 @@
 public class MemberController {
     private final MemberService memberService;
     @PostMapping("/checkId")
+    @Operation(summary = "아이디 중복 체크", description = "서비스에서 사용할 고유 ID를 중복 체크합니다.")
     public ApiResponse<MemberResponseDTO.checkId> checkId(
             @RequestBody final MemberRequestDTO.checkId request
     ) {
         return ApiResponse.onSuccess(memberService.checkId(request));
     }
     @PostMapping("/register")
+    @Operation(summary = "회원가입", description = "회원가입을 진행합니다.")
     public ApiResponse<MemberResponseDTO.registerMember> registerMember(
             @RequestBody final MemberRequestDTO.registerMember request
     ) {

diff --git a/src/main/java/org/example/tree/domain/post/controller/PostController.java b/src/main/java/org/example/tree/domain/post/controller/PostController.java
@@ -1,11 +1,13 @@
 package org.example.tree.domain.post.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
 import lombok.Getter;
 import lombok.RequiredArgsConstructor;
 import org.example.tree.domain.post.dto.PostRequestDTO;
 import org.example.tree.domain.post.dto.PostResponseDTO;
 import org.example.tree.domain.post.service.PostService;
 import org.example.tree.global.common.ApiResponse;
+import org.springframework.http.MediaType;
 import org.springframework.web.bind.annotation.*;
 import org.springframework.web.multipart.MultipartFile;
 
@@ -16,18 +18,19 @@
 public class PostController {
     private final PostService postService;
 
-    @PostMapping("/trees/{treeId}/feed/posts")
+    @PostMapping(value = "/trees/{treeId}/feed/posts", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(summary = "게시글 작성", description = "게시글을 작성합니다.")
     public ApiResponse<PostResponseDTO.createPost> createPost(
             @PathVariable final Long treeId,
             @RequestHeader("Authorization") final String header,
-            @RequestPart final PostRequestDTO.createPost request,
-            @RequestPart(required = false) List<MultipartFile> images
+            @RequestBody final PostRequestDTO.createPost request
     ) throws Exception {
         String token = header.replace("Bearer ", "");
-        return ApiResponse.onSuccess(postService.createPost(treeId, request, images, token));
+        return ApiResponse.onSuccess(postService.createPost(treeId, request, token));
     }
 
     @GetMapping("/trees/{treeId}/feed")
+    @Operation(summary = "피드 조회", description = "특정 트리하우스 속 피드를 불러옵니다.")
     public ApiResponse<List<PostResponseDTO.getFeed>> getFeed(
             @PathVariable final Long treeId,
             @RequestHeader("Authorization") final String header
@@ -37,6 +40,7 @@ public ApiResponse<List<PostResponseDTO.getFeed>> getFeed(
     }
 
     @GetMapping("/trees/{treeId}/feed/posts/{postId}")
+    @Operation(summary = "게시글 조회", description = "특정 게시글을 조회합니다.")
     public ApiResponse<PostResponseDTO.getPost> getPost(
             @PathVariable final Long treeId,
             @PathVariable final Long postId,
@@ -47,6 +51,7 @@ public ApiResponse<PostResponseDTO.getPost> getPost(
     }
 
     @GetMapping("/trees/{treeId}/feed/posts")
+    @Operation(summary = "특정 멤버의 게시글 조회", description = "특정 멤버가 작성한 게시글 목록을 불러옵니다.")
     public ApiResponse<List<PostResponseDTO.getPost>> getPosts(
             @PathVariable final Long treeId,
             @RequestParam(name = "member") final Long profileId,
@@ -57,6 +62,7 @@ public ApiResponse<List<PostResponseDTO.getPost>> getPosts(
     }
 
     @PatchMapping("/trees/{treeId}/feed/posts/{postId}")
+    @Operation(summary = "게시글 수정", description = "게시글을 수정합니다.")
     public ApiResponse updatePost(
             @PathVariable final Long treeId,
             @PathVariable final Long postId,
@@ -69,6 +75,7 @@ public ApiResponse updatePost(
     }
 
     @DeleteMapping("/trees/{treeId}/feed/posts/{postId}")
+    @Operation(summary = "게시글 삭제", description = "게시글을 삭제합니다.")
     public ApiResponse deletePost(
             @PathVariable final Long treeId,
             @PathVariable final Long postId,

diff --git a/src/main/java/org/example/tree/domain/post/converter/PostConverter.java b/src/main/java/org/example/tree/domain/post/converter/PostConverter.java
@@ -49,6 +49,8 @@ public PostResponseDTO.getFeed toGetFeed(Post post, List<ReactionResponseDTO.get
                 .map(PostImage::getImageUrl)
                 .collect(Collectors.toList());
         return PostResponseDTO.getFeed.builder()
+                .postId(post.getId())
+                .postAuthorId(post.getProfile().getId())
                 .profileImageUrl(post.getProfile().getProfileImageUrl())
                 .memberName(post.getProfile().getMemberName())
                 .content(post.getContent())

diff --git a/src/main/java/org/example/tree/domain/post/dto/PostRequestDTO.java b/src/main/java/org/example/tree/domain/post/dto/PostRequestDTO.java
@@ -3,6 +3,7 @@
 import lombok.AccessLevel;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
+import org.springframework.web.multipart.MultipartFile;
 
 import java.util.List;
 
@@ -13,6 +14,7 @@ public class PostRequestDTO {
     @Getter
     public static class createPost {
         private String content;
+        List<MultipartFile> images;
     }
 
     @Getter

diff --git a/src/main/java/org/example/tree/domain/post/dto/PostResponseDTO.java b/src/main/java/org/example/tree/domain/post/dto/PostResponseDTO.java
@@ -27,6 +27,8 @@ public static class createPost {
     @AllArgsConstructor
     public static class getFeed {
 
+        private Long postId;
+        private Long postAuthorId;
         private String profileImageUrl;
         private String memberName;
         private String content;

diff --git a/src/main/java/org/example/tree/domain/post/service/PostService.java b/src/main/java/org/example/tree/domain/post/service/PostService.java
@@ -34,10 +34,8 @@ public class PostService {
     private final PostImageCommandService postImageCommandService;
 
     @Transactional
-    public PostResponseDTO.createPost createPost(Long treeId, PostRequestDTO.createPost request, List<MultipartFile> images, String token) throws Exception {
-        if (images == null) {
-            images = new ArrayList<>();
-        }
+    public PostResponseDTO.createPost createPost(Long treeId, PostRequestDTO.createPost request, String token) throws Exception {
+        List<MultipartFile> images = request.getImages() != null && !request.getImages().isEmpty() ? request.getImages() : new ArrayList<>();
         Profile profile = profileService.getTreeProfile(token, treeId);
         List<PostImage> postImages = postConverter.toPostImages(images);
         Post post = postConverter.toPost(request.getContent(), profile);

diff --git a/src/main/java/org/example/tree/domain/profile/controller/ProfileController.java b/src/main/java/org/example/tree/domain/profile/controller/ProfileController.java
@@ -1,5 +1,6 @@
 package org.example.tree.domain.profile.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
 import lombok.RequiredArgsConstructor;
 import org.example.tree.domain.profile.dto.ProfileRequestDTO;
 import org.example.tree.domain.profile.service.ProfileService;
@@ -15,6 +16,7 @@ public class ProfileController {
     private final ProfileService profileService;
 
     @PostMapping(value = "/trees/owner/register", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(summary = "트리하우스 설립자 프로필 등록", description = "트리하우스 오너 프로필을 등록합니다.")
     public ApiResponse registerTreeOwner(
             @RequestPart ProfileRequestDTO.ownerProfile request,
             @RequestPart("profileImage") final MultipartFile profileImage
@@ -23,6 +25,7 @@ public ApiResponse registerTreeOwner(
     }
 
     @PostMapping(value = "/trees/members/register", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(summary = "트리하우스 멤버 프로필 등록", description = "트리하우스 멤버 프로필을 등록합니다.")
     public ApiResponse registerTreeMember(
             @RequestPart ProfileRequestDTO.createProfile request,
             @RequestPart("profileImage") final MultipartFile profileImage
@@ -31,6 +34,7 @@ public ApiResponse registerTreeMember(
     }
 
     @GetMapping("/trees/{treeId}/members/{profileId}") //프로필 조회
+    @Operation(summary = "멤버 프로필 조회", description = "트리하우스 속 특정 멤버의 프로필을 조회합니다.")
     public ApiResponse getProfileDetails(
             @RequestHeader("Authorization") final String header,
             @PathVariable Long treeId,
@@ -40,6 +44,7 @@ public ApiResponse getProfileDetails(
     }
 
     @GetMapping("/trees/{treeId}/myProfile") //내 프로필 조회
+    @Operation(summary = "내 프로필 조회", description = "트리하우스 속 내 프로필을 조회합니다.")
     public ApiResponse getMyProfile(
             @RequestHeader("Authorization") final String header,
             @PathVariable Long treeId

diff --git a/src/main/java/org/example/tree/domain/reaction/controller/ReactionController.java b/src/main/java/org/example/tree/domain/reaction/controller/ReactionController.java
@@ -1,5 +1,6 @@
 package org.example.tree.domain.reaction.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
 import lombok.RequiredArgsConstructor;
 import org.example.tree.domain.reaction.dto.ReactionRequestDTO;
 import org.example.tree.domain.reaction.service.ReactionService;
@@ -13,6 +14,7 @@ public class ReactionController {
     private final ReactionService reactionService;
 
     @PostMapping("/trees/{treeId}/feed/posts/{postId}/reaction")
+    @Operation(summary = "게시글 리액션", description = "게시글에 리액션을 추가합니다.")
     public ApiResponse createPostReaction(
             @PathVariable Long treeId,
             @PathVariable Long postId,
@@ -25,6 +27,7 @@ public ApiResponse createPostReaction(
     }
 
     @PostMapping("/trees/{treeId}/feed/comments/{commentId}/reaction")
+    @Operation(summary = "댓글 리액션", description = "댓글에 리액션을 추가합니다.")
     public ApiResponse createCommentReaction(
             @PathVariable Long treeId,
             @PathVariable Long commentId,
@@ -37,6 +40,7 @@ public ApiResponse createCommentReaction(
     }
 
     @PostMapping("/trees/{treeId}/feed/replies/{replyId}/reaction")
+    @Operation(summary = "답글 리액션", description = "답글에 리액션을 추가합니다.")
     public ApiResponse createReplyReaction(
             @PathVariable Long treeId,
             @PathVariable Long replyId,

diff --git a/src/main/java/org/example/tree/domain/root/controller/RootController.java b/src/main/java/org/example/tree/domain/root/controller/RootController.java
@@ -1,12 +1,14 @@
 package org.example.tree.domain.root.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 @RestController
 public class RootController {
 
     @GetMapping("/health")
+    @Operation(summary = "서버 상태 확인", description = "서버의 상태를 확인합니다.")
     public String healthCheck(){
         return "I'm healty!";
     }