docs: Update API specification (#82)

Author: beekeeper24

docs/api-specification.yaml

@@ -179,41 +179,57 @@ components:
           description: 메시지 전송 시간
 
     # User Chat Domain Schemas
-    ChatRoom:
+    ChatRoomResponse:
       type: object
       properties:
         id:
           type: integer
           format: int64
           description: 채팅방 고유 식별자
-        roomName:
+        title:
           type: string
-          description: 채팅방 이름
-        creatorId:
+          description: 채팅방 제목(Guide-User 조합)
+        guideId:
           type: integer
           format: int64
-          description: Guest ID (생성자)
-        guideId:
+          description: 가이드 ID
+        userId:
           type: integer
           format: int64
-          description: Guide ID
-        status:
-          type: string
-          enum: [WAITING, ACTIVE, CLOSED]
-          description: 채팅방 상태
-        createdAt:
+          description: 게스트 ID
+        updatedAt:
           type: string
           format: date-time
-          description: 생성 일시
+          description: 최근 메시지 기준 갱신 시각 (Asia/Seoul)
+        lastMessageId:
+          type: integer
+          format: int64
+          nullable: true
+          description: 마지막 메시지 ID (없다면 null)
 
-    UserChatMessage:
+    ChatRoomStartRequest:
+      type: object
+      required:
+        - guideId
+        - userId
+      properties:
+        guideId:
+          type: integer
+          format: int64
+          description: 대화를 시작할 가이드 ID
+        userId:
+          type: integer
+          format: int64
+          description: 채팅을 요청한 사용자 ID
+
+    ChatMessageResponse:
       type: object
       properties:
         id:
           type: integer
           format: int64
           description: 메시지 고유 식별자
-        chatRoomId:
+        roomId:
           type: integer
           format: int64
           description: 채팅방 ID
@@ -227,10 +243,16 @@ components:
         createdAt:
           type: string
           format: date-time
-          description: 메시지 전송 시간
-        isRead:
-          type: boolean
-          description: 읽음 상태
+          description: 메시지 전송 시간 (Asia/Seoul)
+
+    ChatMessageSendRequest:
+      type: object
+      required:
+        - content
+      properties:
+        content:
+          type: string
+          description: 전송할 메시지 내용
 
     # Rating Schemas
     RateTargetType:
@@ -658,7 +680,26 @@ paths:
       tags:
         - userchat
       summary: 내 채팅방 목록 조회
-      description: 사용자가 참여한 채팅방 목록을 조회 (Guest는 생성한 방, Guide는 참여한 방)
+      description: 인증된 사용자가 참여한 채팅방 목록을 최근 업데이트 순으로 돌려줍니다.
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            format: int32
+            default: 20
+            minimum: 1
+            maximum: 100
+          description: 응답에 포함할 최대 채팅방 수 (기본 20)
+        - name: cursor
+          in: query
+          required: false
+          schema:
+            type: string
+          description: "커서 기반 페이지네이션 포인터. '{updatedAt ISO-8601}|{roomId}' 형식이며 이전 응답의 nextCursor를 그대로 전달합니다."
       responses:
         '200':
           description: 채팅방 목록 조회 성공
@@ -670,35 +711,34 @@ paths:
                   - type: object
                     properties:
                       data:
-                        type: array
-                        items:
-                          $ref: '#/components/schemas/ChatRoom'
+                        type: object
+                        properties:
+                          rooms:
+                            type: array
+                            items:
+                              $ref: '#/components/schemas/ChatRoomResponse'
+                          nextCursor:
+                            type: string
+                            nullable: true
+                            description: 다음 페이지 요청 시 사용할 커서 (없으면 null)
 
+  /api/userchat/rooms/start:
     post:
       tags:
         - userchat
-      summary: 새 채팅방 생성 (Guest만 가능)
-      description: Guest가 Guide와의 채팅을 위한 새 채팅방을 생성합니다
+      summary: 1:1 채팅방 생성 또는 재사용
+      description: 가이드-게스트 조합으로 채팅방을 생성하며, 기존 방이 있으면 재사용합니다.
+      security:
+        - BearerAuth: []
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              type: object
-              required:
-                - roomName
-                - guideId
-              properties:
-                roomName:
-                  type: string
-                  description: 채팅방 이름
-                guideId:
-                  type: integer
-                  format: int64
-                  description: 대화할 가이드 ID
+              $ref: '#/components/schemas/ChatRoomStartRequest'
       responses:
-        '201':
-          description: 채팅방 생성 성공
+        '200':
+          description: 채팅방 생성 또는 기존 방 반환
           content:
             application/json:
               schema:
@@ -707,14 +747,50 @@ paths:
                   - type: object
                     properties:
                       data:
-                        $ref: '#/components/schemas/ChatRoom'
+                        $ref: '#/components/schemas/ChatRoomResponse'
+        '403':
+          description: 인증되지 않은 사용자 또는 참여자가 아닙니다.
 
   /api/userchat/rooms/{roomId}:
+    get:
+      tags:
+        - userchat
+      summary: 채팅방 단건 조회
+      description: 채팅방 참여자만 상세 정보를 조회할 수 있습니다.
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: roomId
+          in: path
+          required: true
+          schema:
+            type: integer
+            format: int64
+          description: 채팅방 ID
+      responses:
+        '200':
+          description: 채팅방 조회 성공
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/ChatRoomResponse'
+        '403':
+          description: 채팅방 참여자가 아닙니다.
+        '404':
+          description: 채팅방을 찾을 수 없음
+
     delete:
       tags:
         - userchat
       summary: 채팅방 삭제
-      description: 채팅방과 모든 메시지를 영구적으로 삭제합니다 (생성자만 가능)
+      description: 채팅방과 모든 메시지를 삭제합니다 (생성자만 가능).
+      security:
+        - BearerAuth: []
       parameters:
         - name: roomId
           in: path
@@ -731,7 +807,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/ApiResponse'
         '403':
-          description: 권한 없음 (생성자만 삭제 가능)
+          description: 채팅방 생성자가 아닙니다.
         '404':
           description: 채팅방을 찾을 수 없음
 
@@ -740,7 +816,9 @@ paths:
       tags:
         - userchat
       summary: 채팅방 메시지 조회
-      description: 특정 채팅방의 메시지 이력을 시간순으로 조회
+      description: 특정 채팅방의 메시지를 시간순으로 가져옵니다.
+      security:
+        - BearerAuth: []
       parameters:
         - name: roomId
           in: path
@@ -749,6 +827,23 @@ paths:
             type: integer
             format: int64
           description: 채팅방 ID
+        - name: after
+          in: query
+          required: false
+          schema:
+            type: integer
+            format: int64
+          description: 해당 메시지 ID 이후의 메시지만 조회
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            format: int32
+            default: 50
+            minimum: 1
+            maximum: 200
+          description: 최대 조회 건수 (기본 50)
       responses:
         '200':
           description: 메시지 조회 성공
@@ -760,20 +855,21 @@ paths:
                   - type: object
                     properties:
                       data:
-                        type: object
-                        properties:
-                          room:
-                            $ref: '#/components/schemas/ChatRoom'
-                          messages:
-                            type: array
-                            items:
-                              $ref: '#/components/schemas/UserChatMessage'
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/ChatMessageResponse'
+        '403':
+          description: 채팅방 참여자가 아닙니다.
+        '404':
+          description: 채팅방을 찾을 수 없음
 
     post:
       tags:
         - userchat
       summary: 채팅방에 메시지 전송
-      description: 채팅방에 메시지를 전송합니다 (WebSocket으로도 실시간 전송됨)
+      description: 채팅방에 새 메시지를 전송합니다.
+      security:
+        - BearerAuth: []
       parameters:
         - name: roomId
           in: path
@@ -787,13 +883,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              required:
-                - content
-              properties:
-                content:
-                  type: string
-                  description: 메시지 내용
+              $ref: '#/components/schemas/ChatMessageSendRequest'
       responses:
         '201':
           description: 메시지 전송 성공
@@ -805,7 +895,11 @@ paths:
                   - type: object
                     properties:
                       data:
-                        $ref: '#/components/schemas/UserChatMessage'
+                        $ref: '#/components/schemas/ChatMessageResponse'
+        '403':
+          description: 채팅방 참여자가 아닙니다.
+        '404':
+          description: 채팅방을 찾을 수 없음
 
   # ===================
   # Rate Domain APIs