[EA3-111] feature : 그룹채팅 과거 채팅 페이징 조회 API 구현 및 Swagger 문서 보완

Author: dbrkdgus00

src/main/java/grep/neogul_coder/domain/groupchat/controller/GroupChatRestController.java

@@ -26,7 +26,6 @@ public ApiResponse<PageResponse<GroupChatMessageResponseDto>> getMessages(
         PageResponse<GroupChatMessageResponseDto> pageResponse =
             groupChatService.getMessages(roomId, page, size);
 
-        // 공통 응답 형식에 맞게 반환
         return ApiResponse.success(pageResponse);
     }
 }

src/main/java/grep/neogul_coder/domain/groupchat/controller/GroupChatRestSpecification.java

@@ -15,33 +15,62 @@ public interface GroupChatRestSpecification {
     @Operation(
         summary = "채팅 메시지 페이징 조회",
         description = """
-        채팅방의 과거 메시지를 페이지 단위로 조회합니다. <br>
-        프론트는 무한 스크롤 방식으로 이 API를 반복 호출하여 이전 메시지를 계속 불러올 수 있습니다. <br><br>
-
-        이 API는 WebSocket의 `/sub/chat/room/{roomId}` 실시간 수신과는 별개입니다. <br>
-        사용자는 채팅방 입장 시 이 API로 과거 메시지를 먼저 가져오고 <br>
-        이후 WebSocket을 연결해 실시간 메시지를 받는 방식으로 연동합니다. <br><br>
-
-        전반적인 프론트 흐름은 다음과 같습니다: <br>
-        1. 채팅방에 처음 입장하면 → 이 API로 `page=0`부터 메시지를 조회 <br>
-        2. 이후 스크롤을 올릴 때마다 → `page=1`, `page=2`… 순차 호출 <br>
-        3. 동시에 WebSocket `/sub/chat/room/{roomId}` 구독 시작 <br><br>
-
-        파라미터 설명: <br>
-        - `roomId`: 채팅방 식별자입니다. <br>
-        - `page`: 0부터 시작하는 페이지 번호입니다. (0번이 가장 오래된 메시지입니다.) <br>
-        - `size`: 한 페이지에 포함시킬 메시지 개수입니다. <br>
-        - 메시지는 **오래된 순(오름차순)** 으로 정렬되어 반환됩니다. <br>
-        - 프론트는 최신 메시지를 아래에 배치하고, 스크롤을 위로 올릴 때마다 과거 메시지를 불러오도록 구현합니다. <br><br>
+        이 API는 **채팅방의 과거 메시지**를 페이지 단위로 가져오는 용도입니다.  
+        WebSocket의 실시간 수신(`/sub/chat/room/{roomId}`)과는 별개로,  
+        채팅방에 입장할 때 이전 대화 기록을 불러오는 데 사용됩니다.
         
-
-        응답 구조: <br>
-        - `ApiResponse<PageResponse<...>>` 형태로 감싸져 있습니다. <br>
-        - 실제 메시지는 `content()` 메서드를 통해 꺼낼 수 있습니다. <br>
-        - 페이지네이션 정보는 `currentNumber()`, `prevPage()`, `nextPage()` 등을 통해 확인할 수 있습니다. <br><br>
-
-        예시 요청 URL: `/api/chat/room/1/messages?page=0&size=20`
-    """
+        ---
+        
+        **프론트엔드 연동 흐름 (권장 방식)**:
+        1. **채팅방 입장 시** → `GET /api/chat/room/{roomId}/messages?page=0&size=20` 호출해 최신 메시지 20개 로드  
+        2. **스크롤 위로 올릴 때** → `page=1`, `page=2` ... 순차적으로 과거 메시지를 추가 로딩 (무한 스크롤)  
+        3. **동시에** → WebSocket(`wss://wibby.cedartodo.uk/ws-stomp`) 연결 후 `/sub/chat/room/{roomId}`를 **구독**해 실시간 메시지 수신  
+        
+        ---
+        
+        **파라미터 설명**:
+        - `roomId`: 채팅방 ID  
+        - `page`: 페이지 번호 (0부터 시작, 0 = 최신 메시지 20개)  
+        - `size`: 한 페이지당 메시지 수 (기본값 20)  
+        - 메시지는 **오래된 순(오름차순)**으로 반환됩니다.
+        
+        ---
+        
+        **응답 구조**:
+        - `ApiResponse<PageResponse<GroupChatMessageResponseDto>>` 형태  
+        - `content()`로 메시지 목록 접근 가능  
+        - 페이지네이션 정보: `currentNumber()`, `prevPage()`, `nextPage()` 등
+        
+        ---
+        
+        **예시 요청 URL**:
+        ```
+        /api/chat/room/1/messages?page=0&size=20
+        ```
+        
+        **예시 응답**:
+        ```json
+        {
+          "success": true,
+          "data": {
+            "content": [
+              {
+                "id": 101,
+                "roomId": 1,
+                "senderId": 10,
+                "senderNickname": "유강현",
+                "profileImageUrl": "https://example.com/profile.jpg",
+                "message": "안녕하세요!",
+                "sentAt": "2025-07-21T14:32:00"
+              }
+            ],
+            "currentNumber": 0,
+            "nextPage": 1,
+            "prevPage": null
+          }
+        }
+        ```
+        """
     )
 
     ApiResponse<PageResponse<GroupChatMessageResponseDto>> getMessages(

src/main/java/grep/neogul_coder/domain/groupchat/controller/GroupChatSwaggerSpecification.java

@@ -11,9 +11,58 @@
 @Tag(name = "GroupChat", description = "WebSocket 구조 설명용 Swagger 문서")
 public interface GroupChatSwaggerSpecification {
 
-    @Operation(summary = "Pub 채팅 메시지 전송 구조 예시", description = "실제 채팅 전송은 WebSocket을 통해 `/pub/chat/message`로 전송됩니다.")
+    @Operation(summary = "채팅 메시지 전송 (WebSocket Pub)",
+        description = """
+        **실제 채팅 메시지 전송은 WebSocket 연결 후에 이루어집니다.**
+
+        **1. WebSocket 연결**
+        - 먼저 `wss://wibby.cedartodo.uk/ws-stomp` 엔드포인트로 STOMP 연결을 맺습니다.
+
+        **2. 메시지 전송**
+        - 연결이 완료된 후 `/pub/chat/message` 경로로 메시지를 보냅니다.
+
+        **예시 Request JSON**
+        ```json
+        {
+          "roomId": 1,
+          "senderId": 10,
+          "message": "안녕하세요!"
+        }
+        ```
+
+        ** Swagger에서 이 API를 실행해도 실제 전송은 되지 않으며, 
+        WebSocket 통신 구조를 이해하기 위한 문서 예시입니다.**
+        """)
     ApiResponse<GroupChatSwaggerResponse> sendMessage(GroupChatSwaggerRequest request);
 
-    @Operation(summary = "Sub 채팅 메시지 수신 구조 예시", description = "실제 메시지 수신은 WebSocket을 통해 `/sub/chat/room/{roomId}`로 수신됩니다.")
+    @Operation(summary = "채팅 메시지 수신 (WebSocket Sub)",
+        description = """
+        **실제 메시지 수신 또한 WebSocket 연결이 필수입니다.**
+
+        **1. WebSocket 연결**
+        - 먼저 `wss://wibby.cedartodo.uk/ws-stomp` 엔드포인트로 STOMP 연결을 맺습니다.
+
+        **2. 메시지 구독**
+        - 연결 후 `/sub/chat/room/{roomId}` 경로를 구독(subscribe)하면 해당 채팅방의 새로운 메시지를 실시간으로 수신할 수 있습니다.
+
+        **예시 Subscribe 경로**
+        `/sub/chat/room/1`
+
+        **예시 수신 데이터(JSON)**
+        ```json
+        {
+          "id": 101,
+          "roomId": 1,
+          "senderId": 10,
+          "senderNickname": "유강현",
+          "profileImageUrl": "https://example.com/profile.jpg",
+          "message": "안녕하세요!",
+          "sentAt": "2025-07-21T14:32:00"
+        }
+        ```
+
+        ** Swagger에서는 WebSocket 구독을 테스트할 수 없으며,
+        이 문서는 프론트엔드 구현 참고용입니다.**
+        """)
     ApiResponse<List<GroupChatSwaggerResponse>> getMessages(Long roomId);
 }