[Feat] 프롬프트 상세 조회 및 댓글 CRUD API 계약 및 Swagger 명세 작성

src/main/java/com/promsearch/community/interfaces/CommentController.java

@@ -0,0 +1,77 @@
+package com.promsearch.community.interfaces;
+
+import com.promsearch.community.interfaces.docs.CommentControllerDocs;
+import com.promsearch.community.interfaces.dto.request.CreateCommentRequest;
+import com.promsearch.community.interfaces.dto.request.UpdateCommentRequest;
+import com.promsearch.community.interfaces.dto.response.CommentListResponse;
+import com.promsearch.community.interfaces.dto.response.CommentReplyResponse;
+import com.promsearch.community.interfaces.dto.response.CommentResponse;
+import com.promsearch.global.exception.NotImplementedException;
+import com.promsearch.global.response.ApiResponse;
+import com.promsearch.global.security.AuthenticatedUserPrincipal;
+import jakarta.validation.Valid;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PatchMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@Validated
+@RestController
+@RequestMapping("/api/v1")
+public class CommentController implements CommentControllerDocs {
+
+    @GetMapping("/prompts/{promptId}/comments")
+    @Override
+    public ApiResponse<CommentListResponse> getComments(
+            @PathVariable Long promptId,
+            @AuthenticationPrincipal AuthenticatedUserPrincipal user
+    ) {
+        throw new NotImplementedException("댓글 목록 조회 기능은 아직 구현되지 않았습니다.");
+    }
+
+    @PostMapping("/prompts/{promptId}/comments")
+    @Override
+    public ResponseEntity<ApiResponse<CommentResponse>> createComment(
+            @PathVariable Long promptId,
+            @AuthenticationPrincipal AuthenticatedUserPrincipal user,
+            @Valid @RequestBody CreateCommentRequest request
+    ) {
+        throw new NotImplementedException("댓글 작성 기능은 아직 구현되지 않았습니다.");
+    }
+
+    @PatchMapping("/comments/{commentId}")
+    @Override
+    public ApiResponse<CommentResponse> updateComment(
+            @PathVariable Long commentId,
+            @AuthenticationPrincipal AuthenticatedUserPrincipal user,
+            @Valid @RequestBody UpdateCommentRequest request
+    ) {
+        throw new NotImplementedException("댓글 수정 기능은 아직 구현되지 않았습니다.");
+    }
+
+    @DeleteMapping("/comments/{commentId}")
+    @Override
+    public ApiResponse<Void> deleteComment(
+            @PathVariable Long commentId,
+            @AuthenticationPrincipal AuthenticatedUserPrincipal user
+    ) {
+        throw new NotImplementedException("댓글 삭제 기능은 아직 구현되지 않았습니다.");
+    }
+
+    @PostMapping("/comments/{commentId}/replies")
+    @Override
+    public ResponseEntity<ApiResponse<CommentReplyResponse>> createReply(
+            @PathVariable Long commentId,
+            @AuthenticationPrincipal AuthenticatedUserPrincipal user,
+            @Valid @RequestBody CreateCommentRequest request
+    ) {
+        throw new NotImplementedException("대댓글 작성 기능은 아직 구현되지 않았습니다.");
+    }
+}

src/main/java/com/promsearch/community/interfaces/dto/request/CreateCommentRequest.java

@@ -0,0 +1,12 @@
+package com.promsearch.community.interfaces.dto.request;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
+
+@Schema(description = "댓글 또는 대댓글 작성 요청")
+public record CreateCommentRequest(
+        @Schema(description = "댓글 내용", example = "좋은 프롬프트네요.")
+        @NotBlank(message = "content must not be blank")
+        String content
+) {
+}

src/main/java/com/promsearch/community/interfaces/dto/request/UpdateCommentRequest.java

@@ -0,0 +1,12 @@
+package com.promsearch.community.interfaces.dto.request;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
+
+@Schema(description = "댓글 수정 요청")
+public record UpdateCommentRequest(
+        @Schema(description = "수정할 댓글 내용", example = "수정된 댓글 내용입니다.")
+        @NotBlank(message = "content must not be blank")
+        String content
+) {
+}

src/main/java/com/promsearch/community/interfaces/dto/response/CommentAuthorResponse.java

@@ -0,0 +1,20 @@
+package com.promsearch.community.interfaces.dto.response;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "댓글 작성자 공개 정보")
+public record CommentAuthorResponse(
+        @Schema(description = "작성자 ID", example = "8")
+        Long userId,
+
+        @Schema(description = "작성자 닉네임", example = "홍길동")
+        String nickname,
+
+        @Schema(
+                description = "작성자 프로필 이미지 URL",
+                example = "https://cdn.promsearch.com/profiles/8.jpg",
+                nullable = true
+        )
+        String profileImageUrl
+) {
+}

src/main/java/com/promsearch/community/interfaces/dto/response/CommentListResponse.java

@@ -0,0 +1,11 @@
+package com.promsearch.community.interfaces.dto.response;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.util.List;
+
+@Schema(description = "페이지네이션 없이 전체 댓글을 반환하는 목록 응답")
+public record CommentListResponse(
+        @Schema(description = "작성 시간 내림차순으로 정렬된 최상위 댓글 목록")
+        List<CommentResponse> comments
+) {
+}

src/main/java/com/promsearch/community/interfaces/dto/response/CommentReplyResponse.java

@@ -0,0 +1,36 @@
+package com.promsearch.community.interfaces.dto.response;
+
+import com.promsearch.community.domain.enums.CommentStatus;
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.time.Instant;
+
+@Schema(description = "대댓글 응답")
+public record CommentReplyResponse(
+        @Schema(description = "대댓글 ID", example = "102")
+        Long commentId,
+
+        @Schema(description = "부모 댓글 ID", example = "101")
+        Long parentCommentId,
+
+        @Schema(description = "작성자 정보")
+        CommentAuthorResponse author,
+
+        @Schema(description = "대댓글 내용", example = "저도 그렇게 생각합니다.")
+        String content,
+
+        @Schema(description = "대댓글 상태", example = "ACTIVE")
+        CommentStatus status,
+
+        @Schema(description = "현재 로그인 사용자가 작성한 대댓글인지 여부", example = "true")
+        boolean mine,
+
+        @Schema(description = "프롬프트 작성자가 작성한 대댓글인지 여부", example = "false")
+        boolean promptAuthor,
+
+        @Schema(description = "작성 시각", example = "2026-07-23T03:10:00Z")
+        Instant createdAt,
+
+        @Schema(description = "수정 시각", example = "2026-07-23T03:10:00Z")
+        Instant updatedAt
+) {
+}

src/main/java/com/promsearch/community/interfaces/dto/response/CommentResponse.java

@@ -0,0 +1,40 @@
+package com.promsearch.community.interfaces.dto.response;
+
+import com.promsearch.community.domain.enums.CommentStatus;
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.time.Instant;
+import java.util.List;
+
+@Schema(description = "댓글 및 대댓글 응답")
+public record CommentResponse(
+        @Schema(description = "댓글 ID", example = "101")
+        Long commentId,
+
+        @Schema(description = "부모 댓글 ID. 최상위 댓글이면 null입니다.", example = "100", nullable = true)
+        Long parentCommentId,
+
+        @Schema(description = "작성자 정보")
+        CommentAuthorResponse author,
+
+        @Schema(description = "댓글 내용", example = "좋은 프롬프트네요.")
+        String content,
+
+        @Schema(description = "댓글 상태", example = "ACTIVE")
+        CommentStatus status,
+
+        @Schema(description = "현재 로그인 사용자가 작성한 댓글인지 여부", example = "true")
+        boolean mine,
+
+        @Schema(description = "프롬프트 작성자가 작성한 댓글인지 여부", example = "false")
+        boolean promptAuthor,
+
+        @Schema(description = "작성 시각", example = "2026-07-23T01:30:00Z")
+        Instant createdAt,
+
+        @Schema(description = "수정 시각", example = "2026-07-23T01:30:00Z")
+        Instant updatedAt,
+
+        @Schema(description = "작성 시간 내림차순으로 정렬된 대댓글 목록")
+        List<CommentReplyResponse> replies
+) {
+}

src/main/java/com/promsearch/global/exception/constant/CommonErrorCode.java

@@ -39,4 +39,42 @@ public String getCode() {
     public String getMessage() {
         return message;
     }
+
+    public static final class Examples {
+
+        public static final String BAD_REQUEST = """
+                {
+                  "success": false,
+                  "code": "COMMON-400",
+                  "message": "잘못된 요청입니다."
+                }
+                """;
+
+        public static final String UNAUTHORIZED = """
+                {
+                  "success": false,
+                  "code": "COMMON-401",
+                  "message": "인증이 필요합니다."
+                }
+                """;
+
+        public static final String FORBIDDEN = """
+                {
+                  "success": false,
+                  "code": "COMMON-403",
+                  "message": "허용되지 않는 요청입니다."
+                }
+                """;
+
+        public static final String NOT_FOUND = """
+                {
+                  "success": false,
+                  "code": "COMMON-404",
+                  "message": "요청한 리소스를 찾을 수 없습니다."
+                }
+                """;
+
+        private Examples() {
+        }
+    }
 }

src/main/java/com/promsearch/prompt/domain/Prompt.java

@@ -20,7 +20,7 @@ public class Prompt {
     private final String promptBody;
     private final String thumbnailImage;
     private final PromptOutputType outputType;
-    private final String authorTip;
+    private final String description;
     private final PromptContentType contentType;
     private final PromptStatus status;
     private final Long pricePoint;
@@ -41,7 +41,7 @@ private Prompt(
             String promptBody,
             String thumbnailImage,
             PromptOutputType outputType,
-            String authorTip,
+            String description,
             PromptContentType contentType,
             PromptStatus status,
             Long pricePoint,
@@ -60,7 +60,7 @@ private Prompt(
         this.promptBody = promptBody;
         this.thumbnailImage = thumbnailImage;
         this.outputType = outputType;
-        this.authorTip = authorTip;
+        this.description = description;
         this.contentType = contentType;
         this.status = status;
         this.pricePoint = pricePoint;
@@ -80,7 +80,7 @@ public static Prompt create(
             String promptBody,
             String thumbnailImage,
             PromptOutputType outputType,
-            String authorTip,
+            String description,
             PromptContentType contentType,
             Long pricePoint
     ) {
@@ -93,7 +93,7 @@ public static Prompt create(
                 .promptBody(promptBody)
                 .thumbnailImage(thumbnailImage)
                 .outputType(outputType)
-                .authorTip(authorTip)
+                .description(description)
                 .contentType(contentType)
                 .status(PromptStatus.DRAFT)
                 .pricePoint(pricePoint)
@@ -111,7 +111,7 @@ public static Prompt reconstruct(
             String promptBody,
             String thumbnailImage,
             PromptOutputType outputType,
-            String authorTip,
+            String description,
             PromptContentType contentType,
             PromptStatus status,
             Long pricePoint,
@@ -136,7 +136,7 @@ public static Prompt reconstruct(
                 .promptBody(promptBody)
                 .thumbnailImage(thumbnailImage)
                 .outputType(outputType)
-                .authorTip(authorTip)
+                .description(description)
                 .contentType(contentType)
                 .status(status)
                 .pricePoint(pricePoint)

src/main/java/com/promsearch/prompt/infrastructure/persistence/entity/PostJpaEntity.java

@@ -52,8 +52,8 @@ public class PostJpaEntity extends BaseEntity {
     @Column(name = "output_type", length = 20)
     private PromptOutputType outputType;
 
-    @Column(name = "author_tip", columnDefinition = "TEXT")
-    private String authorTip;
+    @Column(name = "description", columnDefinition = "TEXT")
+    private String description;
 
     @Enumerated(EnumType.STRING)
     @Column(name = "content_type", length = 20)
@@ -83,29 +83,29 @@ public class PostJpaEntity extends BaseEntity {
 
     @Builder(access = AccessLevel.PRIVATE)
     private PostJpaEntity(Long userId, String title, String promptBody, String thumbnailImageUrl,
-                          PromptOutputType outputType, String authorTip, PromptContentType contentType,
+                          PromptOutputType outputType, String description, PromptContentType contentType,
                           Long pricePoint) {
         this.userId = userId;
         this.title = title;
         this.promptBody = promptBody;
         this.thumbnailImageUrl = thumbnailImageUrl;
         this.outputType = outputType;
-        this.authorTip = authorTip;
+        this.description = description;
         this.contentType = contentType;
         this.status = PromptStatus.DRAFT;
         this.pricePoint = pricePoint != null ? pricePoint : 0L;
     }
 
     public static PostJpaEntity create(Long userId, String title, String promptBody, String thumbnailImageUrl,
-                                       PromptOutputType outputType, String authorTip,
+                                       PromptOutputType outputType, String description,
                                        PromptContentType contentType, Long pricePoint) {
         return PostJpaEntity.builder()
                 .userId(userId)
                 .title(title)
                 .promptBody(promptBody)
                 .thumbnailImageUrl(thumbnailImageUrl)
                 .outputType(outputType)
-                .authorTip(authorTip)
+                .description(description)
                 .contentType(contentType)
                 .pricePoint(pricePoint)
                 .build();
@@ -119,7 +119,7 @@ public Prompt toDomain() {
                 promptBody,
                 thumbnailImageUrl,
                 outputType,
-                authorTip,
+                description,
                 contentType,
                 status,
                 pricePoint,