[공통] 팀원 모집 Java Swagger와 공개 API 명세 불일치

[taejinn]

🔍 개요

• 상위 기능 이슈: [공통] 팀원 모집 기능 구현 #2335
• 기준 source: origin/develop@97c3af7f3e211c0bb469272178489f434269bfc4
• 공개 명세 확인일: 2026-08-31
• 심각도: P1 계약 / runtime 자체는 P2
• 분류: 클라이언트 공개 계약 + 서버 Swagger annotation

현재 Java source에는 팀원 모집 operation 23개가 있지만 공개 team-recruitment-api.peridot-ocean.workers.dev/openapi.json에는 22개만 있으며 알림 단건 DELETE가 빠져 있습니다. DTO nullability, timestamp, 필드 우선순위 설명도 runtime과 완전히 정렬되어 있지 않습니다.

🧪 관찰 결과

• 공개 전체 operation: 26개
• 공개 팀원 모집 operation: 22개
• DELETE /team-recruitments/notifications/{notificationId}: 없음
• 현재 Java source의 팀 신규 operation: 23개

기대 동작 / 현재 동작

• 기대: Java에서 생성한 OpenAPI와 공개 계약의 team path/method/status/schema가 같습니다.
• 현재: 클라이언트가 보는 공개 문서와 서버 source가 서로 다른 API를 설명합니다.

📱 클라이언트 영향

클라이언트가 삭제 API를 발견하지 못하거나 nullable 필드를 non-null로 생성할 수 있습니다. TEAM counterpart, GENERAL role, notification optional ID, d_day, timestamp 형식을 정확히 표현해야 합니다.

📦 작업 순서

1. 관련 runtime 정책 이슈와 전역 OpenAPI customizer를 먼저 확정합니다.
2. Java controller/DTO annotation을 canonical source로 정리합니다.
3. source-generated 결과와 공개 artifact의 구조 diff를 검증합니다.

✅ 완료 조건

• 팀 신규 23개 + 기존 참고 API 4개 = 27개 operation이 의도대로 설명됩니다.
• 알림 단건 DELETE가 포함됩니다.
• nullable/required/time format과 실제 JSON이 일치합니다.
• apply_block_reason 우선순위가 실제 source와 일치합니다.
• 모든 $ref와 operationId, response key, 204 body 검사가 통과합니다.

🚫 범위 밖

• Cloudflare 배포는 별도 영향·rollback 설명과 명시적 승인 후 수행합니다.
• 아직 결정되지 않은 runtime 동작을 문서가 먼저 확정하지 않습니다.

[taejinn]

2026-09-03 재점검 결과를 남깁니다.

• docs: 팀원 모집 Java Swagger와 공개 API 계약 동기화 #2391 병합으로 Java OpenAPI 계약 정렬은 반영되었습니다.
• 다만 현재 공개 openapi.json은 전체 26개 operation 상태이며 DELETE /team-recruitments/notifications/{notificationId}가 여전히 포함되지 않아, 이 이슈의 공개 명세 동기화 완료 조건은 아직 충족되지 않았습니다.
• #2408에서 GET /chatroom/team-recruitment가 추가되고 있으므로, 해당 PR 반영 후 공개 명세를 다시 생성·배포하고 operation/path/schema 구조 diff를 검증해야 합니다.

따라서 이 이슈는 닫지 않고 유지합니다.