[Chore] Swagger 문서 도메인 단위로 재정리 + auth/users 설명 보강#63
Conversation
## 대시보드 API 통합 캠페인 대시보드, 평균 시청시간·성별연령·시간대 노출도, 깔대기 그래프, 노출·주목 흐름 그래프 - 4개 태그로 흩어져 있던 홈 대시보드 조회 API 9개(전부 /api/v1/dashboard/campaigns/** 아래)를 "홈 대시보드" 태그 하나로 합쳤다. 각 Docs 인터페이스가 서로 다른 패키지(campaign/vision)에 있었지만 같은 화면의 카드들이라 Swagger에서는 한 곳에 모이게 했다. 태그 통합 과정에서 개별 태그 설명에만 있던 정보(3개 API가 파라미터 틀을 공유한다는 점)는 각 Operation 설명으로 옮겨 유실되지 않게 했다. ## 태그 순서 고정 springdoc이 컨트롤러를 스캔하는 순서는 예측할 수 없어 Swagger UI에서 도메인이 뒤섞여 보였다. SwaggerConfig에 OpenApiCustomizer 빈을 추가해 태그 순서를 고정했다: 인증 → 사용자 → 팀 → 팀원 관리 → 사업자등록증 → 매체 → 캠페인 등록 → 캠페인 페이지 → 홈 대시보드 → 유동인구 적재(관리자). ## auth/users API 문서 보강 AuthTokenController(토큰 재발급), LogoutController(로그아웃), UserController (내 정보 조회) 3개 컨트롤러가 이 코드베이스의 다른 모든 컨트롤러와 달리 Docs 인터페이스가 아예 없어서 Swagger에 @tag도 @operation 설명도 없이 노출되고 있었다. 각각 XControllerDocs 인터페이스를 새로 만들어 토큰 회전/재사용 탐지, CSRF 방어(TrustedOriginValidator), 응답이 ApiResponse 봉투를 쓰지 않는 이유 (Set-Cookie 헤더 필요) 등을 문서화했다. 로컬 서버로 실제 /v3/api-docs를 호출해 태그 순서·설명·엔드포인트 그룹핑이 의도대로 나오는지 확인했다. 순수 문서화 변경이라 기존 테스트는 전부 그대로 통과한다(309개, 0 실패). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 3 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (11)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
LeeJeongHeon02
changed the title
1 participant
Summary
요청 사항 3가지를 처리했다.
1) 홈 대시보드 API 통합 (스캐터링 해결)
"캠페인 대시보드", "평균 시청시간·성별연령·시간대 노출도", "깔대기 그래프", "노출·주목 흐름
그래프" — 4개 태그로 흩어져 있던 홈 대시보드 조회 API 9개(전부
/api/v1/dashboard/campaigns/**)를"홈 대시보드" 태그 하나로 합쳤다. 각 Docs 인터페이스가 서로 다른 패키지(
campaign/vision)에있어서 코드 구조상 갈라져 있었지만, 실제로는 같은 화면의 카드들이라 Swagger에서는 한 곳에
모이게 했다. 태그 통합 과정에서 개별 태그 설명에만 있던 정보(평균 시청시간 등 3개 API가
파라미터 틀을 공유한다는 점)는 유실되지 않게 각 Operation 설명으로 옮겼다.
2) 도메인 단위 정리 — 태그 순서 고정
springdoc이 컨트롤러를 스캔하는 순서는 예측할 수 없어 Swagger UI에서 도메인이 뒤섞여 보였다.
SwaggerConfig에OpenApiCustomizer빈을 추가해 태그 순서를 다음과 같이 고정했다:인증 → 사용자 → 팀 → 팀원 관리 → 사업자등록증 → 매체 → 캠페인 등록 → 캠페인 페이지 → 홈 대시보드 → 유동인구 적재(관리자)
기존에 이미 잘 나뉘어 있던 태그(팀/팀원 관리/사업자등록증, 캠페인 등록/캠페인 페이지 등)는
그대로 두고 순서만 도메인 흐름에 맞게 정렬했다.
3) auth/users API 설명 보강
AuthTokenController(토큰 재발급),LogoutController(로그아웃),UserController(내 정보 조회)3개 컨트롤러가 이 코드베이스의 다른 모든 컨트롤러와 달리 Docs 인터페이스가 아예 없어서 Swagger에
@Tag도@Operation설명도 없이 노출되고 있었다(springdoc 기본 fallback으로만 표시됨). 각각XControllerDocs인터페이스를 새로 만들어 다음을 문서화했다:token_family_id전체 폐기 로직TrustedOriginValidator의 CSRF 방어(Origin/Referer 검증)ApiResponse봉투를 쓰지 않고ResponseEntity를 직접반환하는 이유(
Set-Cookie헤더로 Refresh Token 쿠키를 실어야 함)나타나지 않는다는 점(왜 "로그인" 엔드포인트가 안 보이는지 설명)
Test plan
/v3/api-docs를 직접 호출해 확인:🤖 Generated with Claude Code