waiting-service.json

{"openapi":"3.1.0","info":{"title":"KOK Waiting Service API","description":"웨이팅 등록, 조회, 호출, 입장, 취소 및 매장 웨이팅 설정 API","version":"v1"},"servers":[{"url":"http://localhost:8000","description":"Gateway"}],"tags":[{"name":"Waiting Internal","description":"서비스 내부 호출용 웨이팅 API"},{"name":"Waiting","description":"웨이팅 API"},{"name":"Waiting Setting","description":"매장 웨이팅 설정 API"}],"paths":{"/api/v1/waitings":{"post":{"tags":["Waiting"],"summary":"웨이팅 등록","description":"사용자가 매장에 웨이팅을 등록","operationId":"createWaiting","parameters":[{"name":"X-User-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Role","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaitingCreateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseWaitingResponse"}}}}},"security":[{"Bearer Authentication":[]}]}},"/api/v1/waitings/stores/{storeId}/call-next":{"post":{"tags":["Waiting"],"summary":"다음 순번 웨이팅 호출","description":"OWNER 또는 MASTER가 매장의 다음 웨이팅을 호출","operationId":"callNextWaiting","parameters":[{"name":"X-User-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Role","in":"header","required":false,"schema":{"type":"string"}},{"name":"storeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseWaitingCallResponse"}}}}},"security":[{"Bearer Authentication":[]}]}},"/api/v1/internal/waitings/stores/{storeId}/settings":{"get":{"tags":["Waiting Internal"],"summary":"매장 웨이팅 설정 조회","description":"내부 서비스에서 매장의 웨이팅 설정을 조회","operationId":"getWaitingSetting","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseWaitingSettingResponse"}}}}}},"post":{"tags":["Waiting Internal"],"summary":"매장 웨이팅 설정 초기화","description":"내부 서비스에서 매장의 웨이팅 설정을 초기화","operationId":"initializeWaitingSetting","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaitingSettingInitializeRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseWaitingSettingInitializeResponse"}}}}}}},"/api/v1/internal/waitings/stores/{storeId}/queue/restore":{"post":{"tags":["Waiting Internal"],"summary":"Redis 웨이팅 대기열 복구","description":"DB의 WAITING 상태 데이터를 기준으로 Redis 대기열을 재구성","operationId":"restoreWaitingQueue","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"waitingDate","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseWaitingQueueRestoreResponse"}}}}}}},"/api/v1/waitings/{waitingId}/no-show":{"patch":{"tags":["Waiting"],"summary":"웨이팅 미입장 처리","description":"OWNER 또는 MASTER가 호출된 웨이팅을 미입장 처리","operationId":"noShowWaiting","parameters":[{"name":"X-User-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Role","in":"header","required":false,"schema":{"type":"string"}},{"name":"waitingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaitingNoShowRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseWaitingNoShowResponse"}}}}},"security":[{"Bearer Authentication":[]}]}},"/api/v1/waitings/{waitingId}/enter":{"patch":{"tags":["Waiting"],"summary":"웨이팅 입장 완료 처리","description":"OWNER 또는 MASTER가 호출된 웨이팅을 입장 완료 처리","operationId":"enterWaiting","parameters":[{"name":"X-User-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Role","in":"header","required":false,"schema":{"type":"string"}},{"name":"waitingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseWaitingEnterResponse"}}}}},"security":[{"Bearer Authentication":[]}]}},"/api/v1/waitings/{waitingId}/cancel":{"patch":{"tags":["Waiting"],"summary":"웨이팅 취소","description":"사용자, OWNER 또는 MASTER가 웨이팅을 취소","operationId":"cancelWaiting","parameters":[{"name":"X-User-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Role","in":"header","required":false,"schema":{"type":"string"}},{"name":"waitingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaitingCancelRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseWaitingCancelResponse"}}}}},"security":[{"Bearer Authentication":[]}]}},"/api/v1/waitings/stores/{storeId}/settings":{"patch":{"tags":["Waiting Setting"],"summary":"웨이팅 설정 수정","description":"OWNER 또는 MASTER가 매장의 웨이팅 설정을 수정","operationId":"updateWaitingSetting","parameters":[{"name":"X-User-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Role","in":"header","required":false,"schema":{"type":"string"}},{"name":"storeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaitingSettingUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseWaitingSettingResponse"}}}}},"security":[{"Bearer Authentication":[]}]}},"/api/v1/waitings/{waitingId}":{"get":{"tags":["Waiting"],"summary":"웨이팅 상세 조회","description":"웨이팅 ID로 웨이팅 상세 정보를 조회","operationId":"getWaiting","parameters":[{"name":"X-User-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Role","in":"header","required":false,"schema":{"type":"string"}},{"name":"waitingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseWaitingDetailResponse"}}}}},"security":[{"Bearer Authentication":[]}]}},"/api/v1/waitings/stores/{storeId}":{"get":{"tags":["Waiting"],"summary":"매장별 웨이팅 현황 조회","description":"OWNER 또는 MASTER가 매장의 웨이팅 현황을 상태별로 페이징 조회","operationId":"getStoreWaitings","parameters":[{"name":"X-User-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Role","in":"header","required":false,"schema":{"type":"string"}},{"name":"storeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["WAITING","CALLED","ENTERED","CANCELLED","NO_SHOW"]}},{"name":"page","in":"query","description":"Zero-based page index (0..N)","required":false,"schema":{"type":"integer","default":0,"minimum":0}},{"name":"size","in":"query","description":"The size of the page to be returned","required":false,"schema":{"type":"integer","default":10,"minimum":1}},{"name":"sort","in":"query","description":"Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.","required":false,"schema":{"type":"array","default":["waitingNumber,ASC"],"items":{"type":"string"}}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponsePageResponseStoreWaitingResponse"}}}}},"security":[{"Bearer Authentication":[]}]}},"/api/v1/waitings/me":{"get":{"tags":["Waiting"],"summary":"내 웨이팅 목록 조회","description":"사용자의 웨이팅 목록을 상태별로 페이징 조회","operationId":"getMyWaitings","parameters":[{"name":"X-User-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Role","in":"header","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["WAITING","CALLED","ENTERED","CANCELLED","NO_SHOW"]}},{"name":"page","in":"query","description":"Zero-based page index (0..N)","required":false,"schema":{"type":"integer","default":0,"minimum":0}},{"name":"size","in":"query","description":"The size of the page to be returned","required":false,"schema":{"type":"integer","default":10,"minimum":1}},{"name":"sort","in":"query","description":"Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.","required":false,"schema":{"type":"array","default":["createdAt,DESC"],"items":{"type":"string"}}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponsePageResponseWaitingResponse"}}}}},"security":[{"Bearer Authentication":[]}]}},"/api/v1/internal/waitings/stores/{storeId}/near-turn":{"get":{"tags":["Waiting Internal"],"summary":"순번 임박 알림 대상 조회","description":"현재 순번이 임계값 이내인 웨이팅 목록을 조회","operationId":"getNearTurnWaitings","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"threshold","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":3,"maximum":50,"minimum":1}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseListNearTurnWaitingResponse"}}}}}}}},"components":{"schemas":{"WaitingCreateRequest":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"peopleCount":{"type":"integer","format":"int32"},"requestMessage":{"type":"string","maxLength":500,"minLength":0}},"required":["peopleCount","storeId"]},"ApiResponseWaitingResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/WaitingResponse"}}},"WaitingResponse":{"type":"object","properties":{"waitingId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"storeName":{"type":"string"},"userId":{"type":"string","format":"uuid"},"waitingNumber":{"type":"integer","format":"int64"},"peopleCount":{"type":"integer","format":"int32"},"status":{"type":"string","enum":["WAITING","CALLED","ENTERED","CANCELLED","NO_SHOW"]},"currentRank":{"type":"integer","format":"int64"},"teamsAhead":{"type":"integer","format":"int64"},"createdAt":{"type":"string","format":"date-time"}}},"ApiResponseWaitingCallResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/WaitingCallResponse"}}},"WaitingCallResponse":{"type":"object","properties":{"waitingId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"waitingNumber":{"type":"integer","format":"int64"},"peopleCount":{"type":"integer","format":"int32"},"status":{"type":"string","enum":["WAITING","CALLED","ENTERED","CANCELLED","NO_SHOW"]},"calledAt":{"type":"string","format":"date-time"},"callExpiresAt":{"type":"string","format":"date-time"}}},"WaitingSettingInitializeRequest":{"type":"object","properties":{"waitingEnabled":{"type":"boolean"},"maxWaitingCount":{"type":"integer","format":"int32"},"callTimeoutMinutes":{"type":"integer","format":"int32"},"allowUserCancel":{"type":"boolean"},"averageWaitingMinutes":{"type":"integer","format":"int32"}}},"ApiResponseWaitingSettingInitializeResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/WaitingSettingInitializeResponse"}}},"WaitingSettingInitializeResponse":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"waitingSettingId":{"type":"string","format":"uuid"},"settingCreated":{"type":"boolean"}}},"ApiResponseWaitingQueueRestoreResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/WaitingQueueRestoreResponse"}}},"WaitingQueueRestoreResponse":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"waitingDate":{"type":"string","format":"date"},"restoredCount":{"type":"integer","format":"int32"},"maxWaitingNumber":{"type":"integer","format":"int64"},"restoredAt":{"type":"string","format":"date-time"}}},"WaitingNoShowRequest":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"minLength":0}}},"ApiResponseWaitingNoShowResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/WaitingNoShowResponse"}}},"WaitingNoShowResponse":{"type":"object","properties":{"waitingId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["WAITING","CALLED","ENTERED","CANCELLED","NO_SHOW"]},"reason":{"type":"string"},"noShowAt":{"type":"string","format":"date-time"}}},"ApiResponseWaitingEnterResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/WaitingEnterResponse"}}},"WaitingEnterResponse":{"type":"object","properties":{"waitingId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["WAITING","CALLED","ENTERED","CANCELLED","NO_SHOW"]},"enteredAt":{"type":"string","format":"date-time"}}},"WaitingCancelRequest":{"type":"object","properties":{"cancelReason":{"type":"string","maxLength":500,"minLength":0}}},"ApiResponseWaitingCancelResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/WaitingCancelResponse"}}},"WaitingCancelResponse":{"type":"object","properties":{"waitingId":{"type":"string","format":"uuid"},"waitingNumber":{"type":"integer","format":"int64"},"status":{"type":"string","enum":["WAITING","CALLED","ENTERED","CANCELLED","NO_SHOW"]},"cancelReason":{"type":"string"},"cancelledAt":{"type":"string","format":"date-time"}}},"WaitingSettingUpdateRequest":{"type":"object","properties":{"waitingEnabled":{"type":"boolean"},"maxWaitingCount":{"type":"integer","format":"int32"},"callTimeoutMinutes":{"type":"integer","format":"int32"},"allowUserCancel":{"type":"boolean"},"averageWaitingMinutes":{"type":"integer","format":"int32"}}},"ApiResponseWaitingSettingResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/WaitingSettingResponse"}}},"WaitingSettingResponse":{"type":"object","properties":{"waitingSettingId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"waitingEnabled":{"type":"boolean"},"maxWaitingCount":{"type":"integer","format":"int32"},"callTimeoutMinutes":{"type":"integer","format":"int32"},"allowUserCancel":{"type":"boolean"},"averageWaitingMinutes":{"type":"integer","format":"int32"}}},"ApiResponseWaitingDetailResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/WaitingDetailResponse"}}},"WaitingDetailResponse":{"type":"object","properties":{"waitingId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"storeName":{"type":"string"},"userId":{"type":"string","format":"uuid"},"waitingNumber":{"type":"integer","format":"int64"},"peopleCount":{"type":"integer","format":"int32"},"requestMessage":{"type":"string"},"status":{"type":"string","enum":["WAITING","CALLED","ENTERED","CANCELLED","NO_SHOW"]},"currentRank":{"type":"integer","format":"int64"},"teamsAhead":{"type":"integer","format":"int64"},"calledAt":{"type":"string","format":"date-time"},"enteredAt":{"type":"string","format":"date-time"},"cancelledAt":{"type":"string","format":"date-time"},"cancelReason":{"type":"string"},"noShowAt":{"type":"string","format":"date-time"},"noShowReason":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"ApiResponsePageResponseStoreWaitingResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/PageResponseStoreWaitingResponse"}}},"PageResponseStoreWaitingResponse":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/StoreWaitingResponse"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"},"first":{"type":"boolean"},"last":{"type":"boolean"}}},"StoreWaitingResponse":{"type":"object","properties":{"waitingId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"waitingNumber":{"type":"integer","format":"int64"},"peopleCount":{"type":"integer","format":"int32"},"status":{"type":"string","enum":["WAITING","CALLED","ENTERED","CANCELLED","NO_SHOW"]},"currentRank":{"type":"integer","format":"int64"},"teamsAhead":{"type":"integer","format":"int64"},"requestMessage":{"type":"string"},"calledAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ApiResponsePageResponseWaitingResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/PageResponseWaitingResponse"}}},"PageResponseWaitingResponse":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/WaitingResponse"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"},"first":{"type":"boolean"},"last":{"type":"boolean"}}},"ApiResponseListNearTurnWaitingResponse":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/NearTurnWaitingResponse"}}}},"NearTurnWaitingResponse":{"type":"object","properties":{"waitingId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"currentRank":{"type":"integer","format":"int64"}}}},"securitySchemes":{"Bearer Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}}}