feat: 게시판 api 명세 및 Rest Docs 문서화 (#302)

src/docs/asciidoc/board-api.adoc

@@ -0,0 +1,4 @@
+== 게시판
+
+include::board/post-api.adoc[]
+include::board/comment-api.adoc[]

src/docs/asciidoc/board/comment-api.adoc

@@ -0,0 +1,109 @@
+ifndef::snippet[]
+:snippet: ../../../../build/generated-snippets
+endif::[]
+
+=== 댓글 페이징 조회
+:sectnums!:
+
+==== Request
+include::{snippet}/comment/getCommentsByPaging/http-request.adoc[]
+
+===== Request header
+include::{snippet}/comment/getCommentsByPaging/request-headers.adoc[]
+
+===== Path Parameters
+include::{snippet}/comment/getCommentsByPaging/path-parameters.adoc[]
+
+===== Query Parameters
+include::{snippet}/comment/getCommentsByPaging/query-parameters.adoc[]
+
+==== Response
+include::{snippet}/comment/getCommentsByPaging/http-response.adoc[]
+
+===== Response Body
+include::{snippet}/comment/getCommentsByPaging/response-body.adoc[]
+include::{snippet}/comment/getCommentsByPaging/response-fields.adoc[]
+
+:sectnums:
+
+
+=== 댓글 단건 조회
+:sectnums!:
+
+==== Request
+include::{snippet}/comment/getSingleComment/http-request.adoc[]
+
+===== Request header
+include::{snippet}/comment/getSingleComment/request-headers.adoc[]
+
+===== Path Parameters
+include::{snippet}/comment/getSingleComment/path-parameters.adoc[]
+
+==== Response
+include::{snippet}/comment/getSingleComment/http-response.adoc[]
+
+===== Response Body
+include::{snippet}/comment/getSingleComment/response-body.adoc[]
+include::{snippet}/comment/getSingleComment/response-fields.adoc[]
+
+:sectnums:
+
+
+=== 댓글 생성
+:sectnums!:
+
+==== Request
+include::{snippet}/comment/create/http-request.adoc[]
+
+===== Request header
+include::{snippet}/comment/create/request-headers.adoc[]
+
+===== Request Fields
+include::{snippet}/comment/create/request-fields.adoc[]
+
+===== Path Parameters
+include::{snippet}/comment/create/path-parameters.adoc[]
+
+==== Response
+include::{snippet}/comment/create/http-response.adoc[]
+
+:sectnums:
+
+
+=== 댓글 수정
+:sectnums!:
+
+==== Request
+include::{snippet}/comment/update/http-request.adoc[]
+
+===== Request header
+include::{snippet}/comment/update/request-headers.adoc[]
+
+===== Request Fields
+include::{snippet}/comment/update/request-fields.adoc[]
+
+===== Path Parameters
+include::{snippet}/comment/update/path-parameters.adoc[]
+
+==== Response
+include::{snippet}/comment/update/http-response.adoc[]
+
+:sectnums:
+
+
+=== 댓글 삭제
+:sectnums!:
+
+==== Request
+include::{snippet}/comment/delete/http-request.adoc[]
+
+===== Request header
+include::{snippet}/comment/delete/request-headers.adoc[]
+
+===== Path Parameters
+include::{snippet}/comment/delete/path-parameters.adoc[]
+
+==== Response
+include::{snippet}/comment/delete/http-response.adoc[]
+
+:sectnums:

src/docs/asciidoc/board/post-api.adoc

@@ -0,0 +1,139 @@
+ifndef::snippet[]
+:snippet: ../../../../build/generated-snippets
+endif::[]
+
+=== 게시글 페이징 조회
+:sectnums!:
+
+==== Request
+include::{snippet}/post/getPostsByPaging/http-request.adoc[]
+
+===== Request header
+include::{snippet}/post/getPostsByPaging/request-headers.adoc[]
+
+===== Path Parameters
+include::{snippet}/post/getPostsByPaging/path-parameters.adoc[]
+
+===== Query Parameters
+include::{snippet}/post/getPostsByPaging/query-parameters.adoc[]
+
+==== Response
+include::{snippet}/post/getPostsByPaging/http-response.adoc[]
+
+===== Response Body
+include::{snippet}/post/getPostsByPaging/response-body.adoc[]
+include::{snippet}/post/getPostsByPaging/response-fields.adoc[]
+
+:sectnums:
+
+
+=== 게시글 단건 조회
+:sectnums!:
+
+==== Request
+include::{snippet}/post/getSinglePost/http-request.adoc[]
+
+===== Request header
+include::{snippet}/post/getSinglePost/request-headers.adoc[]
+
+===== Path Parameters
+include::{snippet}/post/getSinglePost/path-parameters.adoc[]
+
+==== Response
+include::{snippet}/post/getSinglePost/http-response.adoc[]
+
+===== Response Body
+include::{snippet}/post/getSinglePost/response-body.adoc[]
+include::{snippet}/post/getSinglePost/response-fields.adoc[]
+
+:sectnums:
+
+
+=== 게시글 등록 (파일 첨부)
+:sectnums!:
+
+==== Request
+include::{snippet}/post/createWithImage/http-request.adoc[]
+
+===== Request header
+include::{snippet}/post/createWithImage/request-headers.adoc[]
+
+===== Path Parameters
+include::{snippet}/post/createWithImage/path-parameters.adoc[]
+
+===== Request Part
+include::{snippet}/post/createWithImage/request-parts.adoc[]
+
+===== Request Part (postRequest)
+include::{snippet}/post/createWithImage/request-part-postRequest-fields.adoc[]
+
+==== Response
+include::{snippet}/post/createWithImage/http-response.adoc[]
+
+:sectnums:
+
+
+=== 게시글 등록 (파일 미첨부)
+:sectnums!:
+
+==== Request
+include::{snippet}/post/createWithoutImage/http-request.adoc[]
+
+===== Request header
+include::{snippet}/post/createWithoutImage/request-headers.adoc[]
+
+===== Path Parameters
+include::{snippet}/post/createWithoutImage/path-parameters.adoc[]
+
+===== Request Part
+include::{snippet}/post/createWithoutImage/request-parts.adoc[]
+
+===== Request Part (postRequest)
+include::{snippet}/post/createWithoutImage/request-part-postRequest-fields.adoc[]
+
+==== Response
+include::{snippet}/post/createWithoutImage/http-response.adoc[]
+
+:sectnums:
+
+
+=== 게시글 수정
+:sectnums!:
+
+==== Request
+include::{snippet}/post/update/http-request.adoc[]
+
+===== Request header
+include::{snippet}/post/update/request-headers.adoc[]
+
+===== Path Parameters
+include::{snippet}/post/update/path-parameters.adoc[]
+
+===== Request Part
+include::{snippet}/post/update/request-parts.adoc[]
+
+===== Request Part (postRequest)
+include::{snippet}/post/update/request-part-postRequest-fields.adoc[]
+
+==== Response
+include::{snippet}/post/update/http-response.adoc[]
+
+:sectnums:
+
+
+=== 게시글 삭제
+:sectnums!:
+
+==== Request
+include::{snippet}/post/delete/http-request.adoc[]
+
+===== Request header
+include::{snippet}/post/delete/request-headers.adoc[]
+
+===== Path Parameters
+include::{snippet}/post/delete/path-parameters.adoc[]
+
+==== Response
+include::{snippet}/post/delete/http-response.adoc[]
+
+:sectnums:

src/docs/asciidoc/index.adoc

@@ -24,6 +24,8 @@ include::event-api.adoc[]
 
 include::form-api.adoc[]
 
+include::board-api.adoc[]
+
 include::notification-api.adoc[]
 
 include::exception-api.adoc[]

src/docs/asciidoc/user/bookmark-api.adoc

@@ -2,6 +2,7 @@ ifndef::snippet[]
 :snippet: ../../../../build/generated-snippets
 endif::[]
 
+
 === 유저가 북마크한 행사 확인
 :sectnums!:
 ==== Request

src/main/java/com/spaceclub/board/controller/CommentController.java

@@ -0,0 +1,107 @@
+package com.spaceclub.board.controller;
+
+import com.spaceclub.board.controller.domain.Comment;
+import com.spaceclub.board.controller.dto.CommentRequest;
+import com.spaceclub.board.controller.dto.CommentResponse;
+import com.spaceclub.board.service.BoardService;
+import com.spaceclub.global.Authenticated;
+import com.spaceclub.global.dto.SliceResponse;
+import com.spaceclub.global.jwt.vo.JwtUser;
+import lombok.RequiredArgsConstructor;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.domain.Slice;
+import org.springframework.data.web.PageableDefault;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.ResponseStatus;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.net.URI;
+import java.util.List;
+
+import static org.springframework.data.domain.Sort.Direction.DESC;
+
+@RestController
+@RequestMapping("/api/v1/boards/posts")
+@RequiredArgsConstructor
+public class CommentController {
+
+    private final BoardService boardService;
+
+    @GetMapping("/{postId}/comments")
+    public SliceResponse<CommentResponse, Comment> getCommentsByPaging(
+            @PageableDefault(sort = "createdAt", direction = DESC) Pageable pageable,
+            @PathVariable Long postId,
+            @Authenticated JwtUser jwtUser
+    ) {
+        // 댓글 페이징 조회
+        Long userId = jwtUser.id();
+        Slice<Comment> commentPages = boardService.getComments(postId, pageable, userId);
+        List<CommentResponse> comments = commentPages.getContent().stream()
+                .map(CommentResponse::of)
+                .toList();
+
+        return new SliceResponse<>(comments, commentPages);
+    }
+
+    @GetMapping("/{postId}/comments/{commentId}")
+    public CommentResponse getSingleComment(
+            @PathVariable Long postId,
+            @PathVariable Long commentId,
+            @Authenticated JwtUser jwtUser
+    ) {
+        // 댓글 단건 조회
+        Long userId = jwtUser.id();
+        Comment comment = boardService.getComment(postId, commentId, userId);
+
+        return CommentResponse.of(comment);
+    }
+
+    @PostMapping("/{postId}/comments")
+    public ResponseEntity<Void> createComment(
+            @RequestBody CommentRequest commentRequest,
+            @PathVariable Long postId,
+            @Authenticated JwtUser jwtUser
+    ) {
+        // 댓글 생성
+        Long userId = jwtUser.id();
+        Long commentId = boardService.createComment(postId, commentRequest, userId);
+
+        return ResponseEntity
+                .status(HttpStatus.CREATED)
+                .location(URI.create("/api/v1/boards/posts/%d/comments/%d".formatted(postId, commentId)))
+                .build();
+    }
+
+    @PutMapping("/{postId}/comments/{commentId}")
+    public void updateComment(
+            @RequestBody CommentRequest commentRequest,
+            @PathVariable Long postId,
+            @PathVariable Long commentId,
+            @Authenticated JwtUser jwtUser
+    ) {
+        // 댓글 수정
+        Long userId = jwtUser.id();
+        boardService.updateComment(postId, commentId, commentRequest, userId);
+    }
+
+    @ResponseStatus(code = HttpStatus.NO_CONTENT)
+    @DeleteMapping("/{postId}/comments/{commentId}")
+    public void deleteComment(
+            @PathVariable Long postId,
+            @PathVariable Long commentId,
+            @Authenticated JwtUser jwtUser
+    ) {
+        // 댓글 삭제
+        Long userId = jwtUser.id();
+        boardService.deleteComment(postId, commentId, userId);
+    }
+
+}