openapi: 3.0.3 info: title: 30damm API description: | 30damm 서비스의 API 명세서입니다. version: 1.0.0 contact: name: developer - xi600 email: excited600@gmail.com servers: - url: http://localhost:8080 description: 로컬 서버 tags: - name: Gatherings description: 모임 - name: Users description: 사용자 - name: Reports description: 신고 paths: /api/v1/users/signup: post: operationId: signup tags: - Users summary: 이메일 회원가입 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SignupRequest' responses: '201': description: 회원가입 성공 content: application/json: schema: $ref: '#/components/schemas/SignupResponse' '400': description: 유효성 검사 실패 '409': description: 이메일 중복 /api/v1/users/login: post: operationId: login tags: - Users summary: 로그인 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LoginRequest' responses: '200': description: 로그인 성공 content: application/json: schema: $ref: '#/components/schemas/LoginResponse' '400': description: 유효성 검사 실패 '401': description: 이메일 또는 비밀번호 불일치 /api/v1/users/refresh: post: operationId: refreshToken tags: - Users summary: 토큰 갱신 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RefreshTokenRequest' responses: '200': description: 토큰 갱신 성공 content: application/json: schema: $ref: '#/components/schemas/RefreshTokenResponse' '401': description: 유효하지 않거나 만료된 리프레시 토큰 /api/v1/users/me: delete: operationId: deleteUser tags: - Users summary: 회원 탈퇴 security: - BearerAuth: [] responses: '204': description: 회원 탈퇴 성공 '401': description: 미인증 /api/v1/gatherings: get: operationId: scrollFilteredGatherings tags: - Gatherings summary: 모임 목록 조회 (커서 기반 페이지네이션) security: - BearerAuth: [] parameters: - name: uuid in: query required: false schema: type: string format: uuid description: Cursor for the page. Omit for the first page. - name: score in: query required: false schema: type: integer description: Score of gatherings. Omit for the first page. - name: size in: query required: true schema: type: integer minimum: 1 maximum: 100 description: Number of gatherings to retrieve per page - name: statuses in: query required: false schema: type: array items: $ref: '#/components/schemas/Gathering_Status' description: Filter gatherings by statuses - name: categories in: query required: false schema: type: array items: $ref: '#/components/schemas/Gathering_Category' description: Filter gatherings by categories - name: guestCount in: query required: false schema: type: integer description: Filter gatherings by current guest count - name: dayOfWeek in: query required: false schema: $ref: '#/components/schemas/Gathering_DayOfWeek' description: Filter gatherings by day of week - name: startDate in: query required: false schema: type: string format: date description: Filter gatherings that start on or after this date - name: endDate in: query required: false schema: type: string format: date description: Filter gatherings that end on or before this date - name: location in: query required: false schema: type: string description: Filter gatherings by location - name: startAge in: query required: false schema: type: integer description: Filter gatherings by minimum age - name: endAge in: query required: false schema: type: integer description: Filter gatherings by maximum age - name: genderRatioEnabled in: query required: false schema: type: boolean description: Filter gatherings by whether gender ratio is enabled - name: minCapacity in: query required: false schema: type: integer description: Filter gatherings by minimum capacity - name: maxCapacity in: query required: false schema: type: integer description: Filter gatherings by maximum capacity - name: minFee in: query required: false schema: type: integer description: Filter gatherings by minimum fee - name: maxFee in: query required: false schema: type: integer description: Filter gatherings by maximum fee responses: '200': description: 모임 목록 조회 성공 content: application/json: schema: $ref: '#/components/schemas/ScrollFilteredGatheringsResponse' '400': description: 유효성 검사 실패 '401': description: 미인증 post: operationId: openGathering tags: - Gatherings summary: 모임 생성 security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OpenGatheringRequest' responses: '201': description: 모임 생성 성공 content: application/json: schema: $ref: '#/components/schemas/OpenGatheringResponse' '400': description: 유효성 검사 실패 '401': description: 미인증 /api/v1/gatherings/{gatheringId}: get: operationId: getGatheringDetail tags: - Gatherings summary: 모임 상세 조회 security: - BearerAuth: [] parameters: - name: gatheringId in: path required: true schema: type: string format: uuid description: 모임 ID (UUIDv7) responses: '200': description: 모임 상세 조회 성공 content: application/json: schema: $ref: '#/components/schemas/GetGatheringDetailResponse' '400': description: 유효성 검사 실패 '401': description: 미인증 '404': description: 모임을 찾을 수 없음 /api/v1/series: post: operationId: scheduleSeries tags: - Gatherings summary: Schedule gatherings based on host setting security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScheduleSeriesRequest' responses: '201': description: Gatherings scheduled successfully '401': description: 미인증 /api/v1/gatherings/{gatheringUuid}/join: post: operationId: joinGathering tags: - Gatherings summary: Join the gathering as a guest security: - BearerAuth: [] parameters: - name: gatheringUuid in: path required: true schema: type: string format: uuid description: The UUID of the gathering to join requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/JoinGatheringRequest' responses: '201': description: Joined gathering successfully '401': description: 미인증 /api/v1/gatherings/{gatheringUuid}/leave: post: operationId: leaveGathering tags: - Gatherings summary: Leave a gathering as a guest security: - BearerAuth: [] parameters: - name: gatheringUuid in: path required: true schema: type: string format: uuid description: The UUID of the gathering to leave requestBody: required: true content: application/json: schema: type: object required: - userUuid - reason properties: userUuid: type: string format: uuid description: UUID of the user leaving the gathering reason: type: string description: Reason for leaving the gathering responses: '204': description: Left gathering successfully '401': description: 미인증 /api/v1/reports: post: operationId: createReport tags: - Reports summary: 콘텐츠 신고 security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReportRequest' responses: '201': description: 신고 접수 성공 content: application/json: schema: $ref: '#/components/schemas/ReportResponse' '400': description: 유효성 검사 실패 '401': description: 미인증 '404': description: 신고 대상을 찾을 수 없음 '409': description: 이미 신고한 대상 /api/v1/blocks/users: post: operationId: blockUser tags: - Blocks summary: 사용자 차단 security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BlockUserRequest' responses: '201': description: 차단 성공 content: application/json: schema: $ref: '#/components/schemas/BlockUserResponse' '400': description: 유효성 검사 실패 '401': description: 미인증 '404': description: 차단 대상을 찾을 수 없음 '409': description: 이미 차단한 사용자 /api/v1/payments/{paymentId}/prepare: post: operationId: preparePayment tags: - Payments summary: Prepare a payment for a gathering parameters: - name: paymentId in: path required: true schema: type: string description: Unique identifier for the payment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PreparePaymentRequest' responses: '200': description: Payment prepared successfully content: application/json: schema: $ref: '#/components/schemas/PreparePaymentResponse' /api/v1/payments/webhook: post: operationId: paymentWebhook tags: - Payments summary: Payment gateway webhook to handle payment notifications requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PaymentWebhook' responses: '200': description: Webhook handled successfully components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT Bearer 토큰 인증 schemas: SignupRequest: type: object required: - email - password - nickname properties: email: type: string format: email description: 유효한 이메일 주소 password: type: string minLength: 8 maxLength: 20 description: 비밀번호 (8~20자) nickname: type: string minLength: 2 maxLength: 10 description: 닉네임 (2~10자) SignupResponse: type: object required: - userUuid - accessToken - refreshToken properties: userUuid: type: string format: uuid description: 사용자 UUID (UUIDv7) accessToken: type: string description: JWT 액세스 토큰 refreshToken: type: string description: JWT 리프레시 토큰 LoginRequest: type: object required: - email - password properties: email: type: string format: email description: 이메일 주소 password: type: string description: 비밀번호 LoginResponse: type: object required: - userUuid - accessToken - refreshToken properties: userUuid: type: string format: uuid description: 사용자 UUID (UUIDv7) accessToken: type: string description: JWT 액세스 토큰 refreshToken: type: string description: JWT 리프레시 토큰 RefreshTokenRequest: type: object required: - refreshToken properties: refreshToken: type: string description: 리프레시 토큰 RefreshTokenResponse: type: object required: - accessToken - refreshToken properties: accessToken: type: string description: 새로운 JWT 액세스 토큰 refreshToken: type: string description: 새로운 JWT 리프레시 토큰 OpenGatheringRequest: type: object required: - title - description - category - minCapacity - maxCapacity - isGenderRatioEnabled - isFree - isSplit properties: title: type: string maxLength: 20 description: 모임 제목 (최대 20자) description: type: string maxLength: 200 description: 모임 설명 (최대 200자) category: $ref: '#/components/schemas/Gathering_Category' location: type: string nullable: true description: 장소 date: type: string format: date nullable: true description: 날짜 (미래 날짜만 가능) startTime: type: string nullable: true description: 시작 시간 (HH:mm, 24시간제) example: '19:00' duration: type: integer nullable: true minimum: 30 description: 소요 시간 (분 단위, 최소 30분) minCapacity: type: integer minimum: 2 description: 최소 인원 (최소 2명) maxCapacity: type: integer description: 최대 인원 (minCapacity 이상) isGenderRatioEnabled: type: boolean description: 성비 제한 활성화 여부 maxMaleCapacity: type: integer nullable: true description: 최대 남성 인원 (isGenderRatioEnabled=true일 때만) maxFemaleCapacity: type: integer nullable: true description: 최대 여성 인원 (isGenderRatioEnabled=true일 때만) isFree: type: boolean description: 무료 여부 price: type: integer nullable: true description: 가격 (원 단위, isFree=false일 때 필수) isSplit: type: boolean description: 더치페이 여부 OpenGatheringResponse: type: object required: - gatheringUuid properties: gatheringUuid: type: string format: uuid description: 생성된 모임 UUID (UUIDv7) ScheduleSeriesRequest: type: object required: - scheduleType - hostUuid - approveType - minCapacity - maxCapacity - genderRatioEnabled - minAge - maxAge - discountEnabled - offline - place - fee - category - subCategory - imageUrl - title - description - gatheringDays properties: scheduleType: $ref: '#/components/schemas/Gathering_ScheduleType' hostUuid: type: string format: uuid description: UUID of the host. tmp property approveType: $ref: '#/components/schemas/Gathering_ApproveType' minCapacity: type: integer description: Minimum capacity of the gathering maxCapacity: type: integer description: Maximum capacity of the gathering maxMaleCount: type: integer description: Maximum number of male guests maxFemaleCount: type: integer description: Maximum number of female guests genderRatioEnabled: type: boolean description: If host can set gender ratio for the gathering minAge: type: integer description: Minimum age of guests maxAge: type: integer description: Maximum age of guests fee: type: integer description: Fee to join the gathering discountEnabled: type: boolean description: If host can set discount strategy for the gathering offline: type: boolean description: If the gathering is offline place: type: string description: Place where the gathering will be held category: $ref: '#/components/schemas/Gathering_Category' subCategory: $ref: '#/components/schemas/Gathering_SubCategory' imageUrl: type: string description: URL of the gathering image title: type: string description: Title of the gathering description: type: string description: Description of the gathering gatheringDays: type: integer description: Number of days before the gathering will take place. discriminator: propertyName: scheduleType mapping: WEEKLY: '#/components/schemas/WeeklyScheduleSeriesRequest' DATE: '#/components/schemas/DateScheduleSeriesRequest' WeeklyScheduleSeriesRequest: allOf: - $ref: '#/components/schemas/ScheduleSeriesRequest' - type: object required: - startDate - endDate - summaries properties: startDate: type: string format: date description: Start date for this day of week schedule endDate: type: string format: date description: End date for this day of week schedule summaries: type: array description: List of Schedule summaries for this day of week schedule items: $ref: '#/components/schemas/Gathering_WeeklyScheduleSummary' DateScheduleSeriesRequest: allOf: - $ref: '#/components/schemas/ScheduleSeriesRequest' - type: object required: - summaries properties: summaries: type: array description: List of Date Schedule summaries items: $ref: '#/components/schemas/Gathering_DateScheduleSummary' Gathering: type: object required: - uuid - hostUuid - approveType - minCapacity - maxCapacity - genderRatioEnabled - minAge - maxAge - totalGuests - fee - discountEnabled - offline - place - category - subCategory - status - imageUrl - title - introduction - clickCount - startDateTime properties: uuid: type: string format: uuid description: UUID of the gathering hostUuid: type: string format: uuid description: UUID of the host. tmp property approveType: $ref: '#/components/schemas/Gathering_ApproveType' minCapacity: type: integer description: Minimum capacity of the gathering maxCapacity: type: integer description: Maximum capacity of the gathering genderRatioEnabled: type: boolean description: If host can set gender ratio for the gathering minAge: type: integer description: Minimum age of guests maxAge: type: integer description: Maximum age of guests maxMaleCount: type: integer description: Maximum number of male guests maxFemaleCount: type: integer description: Maximum number of female guests totalGuests: type: integer description: Total number of guests fee: type: integer description: Fee to join the gathering discountEnabled: type: boolean description: If host can set discount strategy for the gathering offline: type: boolean description: If the gathering is offline place: type: string description: Place where the gathering will be held category: $ref: '#/components/schemas/Gathering_Category' subCategory: $ref: '#/components/schemas/Gathering_SubCategory' status: $ref: '#/components/schemas/Gathering_Status' imageUrl: type: string description: URL of the gathering image title: type: string description: Title of the gathering introduction: type: string description: Introduction of the gathering clickCount: type: integer description: Number of clicks on the gathering startDateTime: type: string format: date-time description: Start date and time of the gathering duration: type: number format: float description: Duration of the gathering in hours (can contain decimals) ScrollFilteredGatheringsResponse: type: object required: - hasNext - list properties: cursor: type: object properties: score: type: integer uuid: type: string format: uuid hasNext: type: boolean list: type: array items: type: object required: - gatheringUuid - title - maleCount - femaleCount - host - isFree - isSplit properties: gatheringUuid: type: string format: uuid description: 모임 UUID (UUIDv7) imgUrl: type: string format: uri nullable: true description: 대표 이미지 URL title: type: string description: 모임 제목 location: type: string nullable: true description: 장소 date: type: string format: date nullable: true description: 날짜 (YYYY-MM-DD) startTime: type: string nullable: true description: 시작 시간 (HH:mm, 24시간제) example: '19:00' duration: type: integer nullable: true description: 소요 시간 (시간 단위) maleCount: type: integer description: 현재 남성 참여 수 femaleCount: type: integer description: 현재 여성 참여 수 host: type: object required: - userUuid - nickname - gender - viewerRelation properties: userUuid: type: string format: uuid description: 호스트 UUID nickname: type: string description: 호스트 닉네임 profileImageUrl: type: string format: uri nullable: true description: 호스트 프로필 이미지 URL gender: $ref: '#/components/schemas/Gender' viewerRelation: $ref: '#/components/schemas/ViewerRelation' isFree: type: boolean description: 무료 여부 isSplit: type: boolean description: 더치페이 여부 price: type: integer nullable: true description: 가격 (원 단위) GetGatheringDetailResponse: type: object required: - gatheringUuid - title - description - host - guests - category - minCapacity - maxCapacity - isGenderRatioEnabled - currentMaleCount - currentFemaleCount - isFree - isSplit - userStatus properties: gatheringUuid: type: string format: uuid description: 모임 UUID (UUIDv7) imgUrl: type: string format: uri nullable: true description: 대표 이미지 URL title: type: string description: 모임 제목 description: type: string description: 모임 설명 host: type: object required: - userUuid - nickname - gender - viewerRelation properties: userUuid: type: string format: uuid description: 호스트 UUID nickname: type: string description: 호스트 닉네임 profileImageUrl: type: string format: uri nullable: true description: 호스트 프로필 이미지 URL gender: $ref: '#/components/schemas/Gender' viewerRelation: $ref: '#/components/schemas/ViewerRelation' guests: type: array description: 참여 게스트 목록 (빈 배열 가능) items: type: object required: - userUuid - nickname - gender - viewerRelation properties: userUuid: type: string format: uuid description: 게스트 UUID nickname: type: string description: 닉네임 profileImageUrl: type: string format: uri nullable: true description: 프로필 이미지 URL gender: $ref: '#/components/schemas/Gender' viewerRelation: $ref: '#/components/schemas/ViewerRelation' category: $ref: '#/components/schemas/Gathering_Category' minCapacity: type: integer description: 최소 인원 maxCapacity: type: integer description: 최대 인원 isGenderRatioEnabled: type: boolean description: 성비 제한 활성화 여부 maxMaleCapacity: type: integer nullable: true description: 최대 남성 인원 maxFemaleCapacity: type: integer nullable: true description: 최대 여성 인원 currentMaleCount: type: integer description: 현재 남성 참여 수 currentFemaleCount: type: integer description: 현재 여성 참여 수 date: type: string format: date nullable: true description: 날짜 (YYYY-MM-DD) startTime: type: string nullable: true description: 시작 시간 (HH:mm, 24시간제) example: '19:00' duration: type: integer nullable: true description: 소요 시간 (시간 단위) location: type: string nullable: true description: 장소 isFree: type: boolean description: 무료 여부 isSplit: type: boolean description: 더치페이 여부 price: type: integer nullable: true description: 가격 (원 단위) userStatus: $ref: '#/components/schemas/GatheringUserStatus' JoinGatheringRequest: type: object properties: confirmPaymentRequest: $ref: '#/components/schemas/ConfirmPaymentRequest' ReportRequest: type: object required: - targetType - targetUuid - reason properties: targetType: type: string enum: - USER - GATHERING description: 신고 대상 유형 targetUuid: type: string format: uuid description: 신고 대상 UUID reason: type: string enum: - OFFENSIVE_CONTENT - ILLEGAL_OR_FALSE_INFO - OTHER description: 신고 사유 description: type: string maxLength: 500 description: 신고 상세 설명 (선택) ReportResponse: type: object required: - reportUuid - status properties: reportUuid: type: string format: uuid description: 생성된 신고 UUID status: type: string enum: - PENDING - REVIEWED - RESOLVED - DISMISSED description: 신고 상태 BlockUserRequest: type: object required: - blockedUserUuid properties: blockedUserUuid: type: string format: uuid description: 차단할 사용자 UUID BlockUserResponse: type: object required: - uuid - blockedUserUuid properties: uuid: type: string format: uuid description: 차단 레코드 UUID blockedUserUuid: type: string format: uuid description: 차단된 사용자 UUID PreparePaymentRequest: type: object required: - productType - productUuid - productName - amount - buyerUuid - buyerEmail - buyerName - buyerPhone properties: productType: $ref: '#/components/schemas/ProductType' productUuid: type: string format: uuid description: UUID of the product being purchased productName: type: string description: Name of the product being purchased amount: type: integer description: Total amount for the payment in Won(KRW) buyerUuid: type: string format: uuid description: UUID of the buyer buyerEmail: type: string format: email description: Email address of the buyer buyerName: type: string description: Name of the buyer buyerPhone: type: string description: Phone number of the buyer PreparePaymentResponse: type: object required: - paymentId - storeId - channelKey properties: paymentId: type: string description: Unique identifier for the payment. It is generated by front app. storeId: type: string description: Identifier for the store where the payment is being processed. channelKey: type: string description: Key representing the payment channel used. PaymentWebhook: type: object required: - type - timestamp - data properties: type: $ref: '#/components/schemas/WebhookType' timestamp: type: string format: date-time description: Unix timestamp when the webhook event was generated data: $ref: '#/components/schemas/WebhookData' Gathering_Status: type: string enum: - OPEN_PENDING - OPEN - CLOSED - IN_PROGRESS - FINISHED description: Status of the gathering Gathering_Category: type: string enum: - NONE - PARTY - FOOD_DRINK - ACTIVITY description: Category of the gathering Gathering_DayOfWeek: type: string enum: - SUNDAY - MONDAY - TUESDAY - WEDNESDAY - THURSDAY - FRIDAY - SATURDAY description: Day of the week Gender: type: string enum: - MALE - FEMALE description: Gender of the user ViewerRelation: type: string enum: - SELF - STRANGER - BLOCKED description: 조회한 사용자와의 관계 GatheringUserStatus: type: string enum: - HOST_OPENED - GUEST_JOINED - GUEST_NOT_JOINED description: 현재 사용자의 모임 참여 상태 Gathering_WeeklyScheduleSummary: type: object required: - startDayOfWeek - startTime properties: startDayOfWeek: $ref: '#/components/schemas/Gathering_DayOfWeek' startTime: type: string format: time description: Start time of the gathering on the specified day of week duration: type: number format: float description: Duration in hours (can contain decimals) Gathering_DateScheduleSummary: type: object required: - startDate - startTime - duration properties: startDate: type: string format: date description: Start date of the gathering startTime: type: string format: time description: Start time of the gathering on the specified date duration: type: number format: float description: Duration in hours (can contain decimals) Gathering_ScheduleType: type: string enum: - WEEKLY - DATE description: Type of scheduling for the gatherings Gathering_ApproveType: type: string enum: - FIRST_IN - APPROVAL description: Ways how to approve guests to join the gathering Gathering_SubCategory: type: string enum: - HOME_PARTY description: Sub-category of the gathering ConfirmPaymentRequest: type: object required: - paymentId - paymentToken - txId - amount properties: paymentId: type: string description: Unique identifier for the payment. It is generated by front app. paymentToken: type: string description: Token received from the payment gateway to verify the payment txId: type: string description: Transaction ID provided by the payment gateway amount: type: integer description: Amount to be payed in Won(KRW) ProductType: type: string enum: - GATHERING description: Type of the product WebhookType: type: string enum: - Transaction.Ready - Transaction.Paid - Transaction.VirtualAccountIssued - Transaction.PartialCancelled - Transaction.Cancelled - Transaction.Failed - Transaction.PayPending - Transaction.CancelPending - Transaction.DisputeCreated - Transaction.DisputeResolved description: Type of the payment webhook event WebhookData: type: object required: - storeId - paymentId - transactionId properties: storeId: type: string description: Identifier for the store or merchant paymentId: type: string description: Unique identifier for the payment transactionId: type: string description: Unique identifier for the transaction cancellationId: type: string description: Unique identifier for the cancellation