Skip to content

Commit 206fb66

Browse files
beekeeper24beekeeper24
committed
docs: Update API specification
1 parent 3ab83e1 commit 206fb66

File tree

1 file changed

+154
-60
lines changed

1 file changed

+154
-60
lines changed

‎docs/api-specification.yaml‎

Lines changed: 154 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -179,41 +179,57 @@ components:
179179
description: 메시지 전송 시간
180180

181181
# User Chat Domain Schemas
182-
ChatRoom:
182+
ChatRoomResponse:
183183
type: object
184184
properties:
185185
id:
186186
type: integer
187187
format: int64
188188
description: 채팅방 고유 식별자
189-
roomName:
189+
title:
190190
type: string
191-
description: 채팅방 이름
192-
creatorId:
191+
description: 채팅방 제목(Guide-User 조합)
192+
guideId:
193193
type: integer
194194
format: int64
195-
description: Guest ID (생성자)
196-
guideId:
195+
description: 가이드 ID
196+
userId:
197197
type: integer
198198
format: int64
199-
description: Guide ID
200-
status:
201-
type: string
202-
enum: [WAITING, ACTIVE, CLOSED]
203-
description: 채팅방 상태
204-
createdAt:
199+
description: 게스트 ID
200+
updatedAt:
205201
type: string
206202
format: date-time
207-
description: 생성 일시
203+
description: 최근 메시지 기준 갱신 시각 (Asia/Seoul)
204+
lastMessageId:
205+
type: integer
206+
format: int64
207+
nullable: true
208+
description: 마지막 메시지 ID (없다면 null)
208209

209-
UserChatMessage:
210+
ChatRoomStartRequest:
211+
type: object
212+
required:
213+
- guideId
214+
- userId
215+
properties:
216+
guideId:
217+
type: integer
218+
format: int64
219+
description: 대화를 시작할 가이드 ID
220+
userId:
221+
type: integer
222+
format: int64
223+
description: 채팅을 요청한 사용자 ID
224+
225+
ChatMessageResponse:
210226
type: object
211227
properties:
212228
id:
213229
type: integer
214230
format: int64
215231
description: 메시지 고유 식별자
216-
chatRoomId:
232+
roomId:
217233
type: integer
218234
format: int64
219235
description: 채팅방 ID
@@ -227,10 +243,16 @@ components:
227243
createdAt:
228244
type: string
229245
format: date-time
230-
description: 메시지 전송 시간
231-
isRead:
232-
type: boolean
233-
description: 읽음 상태
246+
description: 메시지 전송 시간 (Asia/Seoul)
247+
248+
ChatMessageSendRequest:
249+
type: object
250+
required:
251+
- content
252+
properties:
253+
content:
254+
type: string
255+
description: 전송할 메시지 내용
234256

235257
# Rating Schemas
236258
RateTargetType:
@@ -658,7 +680,26 @@ paths:
658680
tags:
659681
- userchat
660682
summary: 내 채팅방 목록 조회
661-
description: 사용자가 참여한 채팅방 목록을 조회 (Guest는 생성한 방, Guide는 참여한 방)
683+
description: 인증된 사용자가 참여한 채팅방 목록을 최근 업데이트 순으로 돌려줍니다.
684+
security:
685+
- BearerAuth: []
686+
parameters:
687+
- name: limit
688+
in: query
689+
required: false
690+
schema:
691+
type: integer
692+
format: int32
693+
default: 20
694+
minimum: 1
695+
maximum: 100
696+
description: 응답에 포함할 최대 채팅방 수 (기본 20)
697+
- name: cursor
698+
in: query
699+
required: false
700+
schema:
701+
type: string
702+
description: "커서 기반 페이지네이션 포인터. '{updatedAt ISO-8601}|{roomId}' 형식이며 이전 응답의 nextCursor를 그대로 전달합니다."
662703
responses:
663704
'200':
664705
description: 채팅방 목록 조회 성공
@@ -670,35 +711,34 @@ paths:
670711
- type: object
671712
properties:
672713
data:
673-
type: array
674-
items:
675-
$ref: '#/components/schemas/ChatRoom'
714+
type: object
715+
properties:
716+
rooms:
717+
type: array
718+
items:
719+
$ref: '#/components/schemas/ChatRoomResponse'
720+
nextCursor:
721+
type: string
722+
nullable: true
723+
description: 다음 페이지 요청 시 사용할 커서 (없으면 null)
676724

725+
/api/userchat/rooms/start:
677726
post:
678727
tags:
679728
- userchat
680-
summary: 새 채팅방 생성 (Guest만 가능)
681-
description: Guest가 Guide와의 채팅을 위한 새 채팅방을 생성합니다
729+
summary: 1:1 채팅방 생성 또는 재사용
730+
description: 가이드-게스트 조합으로 채팅방을 생성하며, 기존 방이 있으면 재사용합니다.
731+
security:
732+
- BearerAuth: []
682733
requestBody:
683734
required: true
684735
content:
685736
application/json:
686737
schema:
687-
type: object
688-
required:
689-
- roomName
690-
- guideId
691-
properties:
692-
roomName:
693-
type: string
694-
description: 채팅방 이름
695-
guideId:
696-
type: integer
697-
format: int64
698-
description: 대화할 가이드 ID
738+
$ref: '#/components/schemas/ChatRoomStartRequest'
699739
responses:
700-
'201':
701-
description: 채팅방 생성 성공
740+
'200':
741+
description: 채팅방 생성 또는 기존 방 반환
702742
content:
703743
application/json:
704744
schema:
@@ -707,14 +747,50 @@ paths:
707747
- type: object
708748
properties:
709749
data:
710-
$ref: '#/components/schemas/ChatRoom'
750+
$ref: '#/components/schemas/ChatRoomResponse'
751+
'403':
752+
description: 인증되지 않은 사용자 또는 참여자가 아닙니다.
711753

712754
/api/userchat/rooms/{roomId}:
755+
get:
756+
tags:
757+
- userchat
758+
summary: 채팅방 단건 조회
759+
description: 채팅방 참여자만 상세 정보를 조회할 수 있습니다.
760+
security:
761+
- BearerAuth: []
762+
parameters:
763+
- name: roomId
764+
in: path
765+
required: true
766+
schema:
767+
type: integer
768+
format: int64
769+
description: 채팅방 ID
770+
responses:
771+
'200':
772+
description: 채팅방 조회 성공
773+
content:
774+
application/json:
775+
schema:
776+
allOf:
777+
- $ref: '#/components/schemas/ApiResponse'
778+
- type: object
779+
properties:
780+
data:
781+
$ref: '#/components/schemas/ChatRoomResponse'
782+
'403':
783+
description: 채팅방 참여자가 아닙니다.
784+
'404':
785+
description: 채팅방을 찾을 수 없음
786+
713787
delete:
714788
tags:
715789
- userchat
716790
summary: 채팅방 삭제
717-
description: 채팅방과 모든 메시지를 영구적으로 삭제합니다 (생성자만 가능)
791+
description: 채팅방과 모든 메시지를 삭제합니다 (생성자만 가능).
792+
security:
793+
- BearerAuth: []
718794
parameters:
719795
- name: roomId
720796
in: path
@@ -731,7 +807,7 @@ paths:
731807
schema:
732808
$ref: '#/components/schemas/ApiResponse'
733809
'403':
734-
description: 권한 없음 (생성자만 삭제 가능)
810+
description: 채팅방 생성자가 아닙니다.
735811
'404':
736812
description: 채팅방을 찾을 수 없음
737813

@@ -740,7 +816,9 @@ paths:
740816
tags:
741817
- userchat
742818
summary: 채팅방 메시지 조회
743-
description: 특정 채팅방의 메시지 이력을 시간순으로 조회
819+
description: 특정 채팅방의 메시지를 시간순으로 가져옵니다.
820+
security:
821+
- BearerAuth: []
744822
parameters:
745823
- name: roomId
746824
in: path
@@ -749,6 +827,23 @@ paths:
749827
type: integer
750828
format: int64
751829
description: 채팅방 ID
830+
- name: after
831+
in: query
832+
required: false
833+
schema:
834+
type: integer
835+
format: int64
836+
description: 해당 메시지 ID 이후의 메시지만 조회
837+
- name: limit
838+
in: query
839+
required: false
840+
schema:
841+
type: integer
842+
format: int32
843+
default: 50
844+
minimum: 1
845+
maximum: 200
846+
description: 최대 조회 건수 (기본 50)
752847
responses:
753848
'200':
754849
description: 메시지 조회 성공
@@ -760,20 +855,21 @@ paths:
760855
- type: object
761856
properties:
762857
data:
763-
type: object
764-
properties:
765-
room:
766-
$ref: '#/components/schemas/ChatRoom'
767-
messages:
768-
type: array
769-
items:
770-
$ref: '#/components/schemas/UserChatMessage'
858+
type: array
859+
items:
860+
$ref: '#/components/schemas/ChatMessageResponse'
861+
'403':
862+
description: 채팅방 참여자가 아닙니다.
863+
'404':
864+
description: 채팅방을 찾을 수 없음
771865

772866
post:
773867
tags:
774868
- userchat
775869
summary: 채팅방에 메시지 전송
776-
description: 채팅방에 메시지를 전송합니다 (WebSocket으로도 실시간 전송됨)
870+
description: 채팅방에 새 메시지를 전송합니다.
871+
security:
872+
- BearerAuth: []
777873
parameters:
778874
- name: roomId
779875
in: path
@@ -787,13 +883,7 @@ paths:
787883
content:
788884
application/json:
789885
schema:
790-
type: object
791-
required:
792-
- content
793-
properties:
794-
content:
795-
type: string
796-
description: 메시지 내용
886+
$ref: '#/components/schemas/ChatMessageSendRequest'
797887
responses:
798888
'201':
799889
description: 메시지 전송 성공
@@ -805,7 +895,11 @@ paths:
805895
- type: object
806896
properties:
807897
data:
808-
$ref: '#/components/schemas/UserChatMessage'
898+
$ref: '#/components/schemas/ChatMessageResponse'
899+
'403':
900+
description: 채팅방 참여자가 아닙니다.
901+
'404':
902+
description: 채팅방을 찾을 수 없음
809903

810904
# ===================
811905
# Rate Domain APIs

0 commit comments

Comments
 (0)