fix: API 문서 내용 불일치 수정

[dh2906]

🔍 개요

• close #이슈번호

---

🚀 주요 변경 내용

• API 구현 내용과 스웨거 문서화된 내용 중 불일치한 부분을 수정했습니다.

• 내부 인프라 용으로 사용하는 엔드포인트에 대해 스웨거 숨김처리 했습니다.

---

💬 참고 사항

---

✅ Checklist (완료 조건)

• 코드 스타일 가이드 준수
• 테스트 코드 포함됨
• Reviewers / Assignees / Labels 지정 완료
• 보안 및 민감 정보 검증 (API 키, 환경 변수, 개인정보 등)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3bcda6e and 5d36f85.

📒 Files selected for processing (5)

• src/main/java/gg/agit/konect/domain/club/controller/ClubApplicationApi.java
• src/main/java/gg/agit/konect/domain/club/controller/ClubBasicApi.java
• src/main/java/gg/agit/konect/domain/club/controller/ClubMemberApi.java
• src/main/java/gg/agit/konect/global/config/SwaggerUiResourceController.java
• src/main/java/gg/agit/konect/infrastructure/slack/ai/SlackEventController.java

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (2)

src/main/java/**/*.java

⚙️ CodeRabbit configuration file

src/main/java/**/*.java: 아래 원칙으로 리뷰 코멘트를 작성한다.

• 코멘트는 반드시 한국어로 작성한다.
• 반드시 수정이 필요한 항목만 코멘트로 남기고, 단순 취향 차이는 지적하지 않는다.
• 각 코멘트 첫 줄에 심각도를 [LEVEL: high|medium|low] 형식으로 반드시 표기한다.
• 심각도 기준: high=운영 장애 가능, medium=품질 저하, low=개선 권고.
• 각 코멘트는 "문제 -> 영향 -> 제안" 순서로 3문장 이내로 간결하게 작성한다.
• 가능하면 재현 조건 및 실패 시나리오도 포함한다.
• 제안은 현재 코드베이스(Spring Boot + JPA + Flyway) 패턴과 일치해야 한다.
• 보안, 트랜잭션 경계, 예외 처리, N+1, 성능 회귀 가능성을 우선 점검한다.
• 가독성: 변수/메서드 이름이 의도를 바로 드러내는지, 중첩과 메서드 길이가 과도하지 않은지 점검한다.
• 단순화: 불필요한 추상화, 중복 로직, 과한 방어 코드가 있으면 더 단순한 대안을 제시한다.
• 확장성: 새 요구사항 추가 시 변경 범위가 최소화되는 구조인지(하드코딩 분기/값 여부 포함) 점검한다.

Files:

• src/main/java/gg/agit/konect/domain/club/controller/ClubMemberApi.java
• src/main/java/gg/agit/konect/global/config/SwaggerUiResourceController.java
• src/main/java/gg/agit/konect/domain/club/controller/ClubApplicationApi.java
• src/main/java/gg/agit/konect/infrastructure/slack/ai/SlackEventController.java
• src/main/java/gg/agit/konect/domain/club/controller/ClubBasicApi.java

**/*

⚙️ CodeRabbit configuration file

**/*: 공통 리뷰 톤 가이드:

• 모든 코멘트는 첫 줄에 [LEVEL: ...] 태그를 포함한다.
• 과장된 표현 없이 사실 기반으로 작성한다.
• 한 코멘트에는 하나의 이슈만 다룬다.
• 코드 예시가 필요하면 최소 수정 예시를 제시한다.
• 가독성/단순화/확장성 이슈를 발견하면 우선순위를 높여 코멘트한다.

Files:

• src/main/java/gg/agit/konect/domain/club/controller/ClubMemberApi.java
• src/main/java/gg/agit/konect/global/config/SwaggerUiResourceController.java
• src/main/java/gg/agit/konect/domain/club/controller/ClubApplicationApi.java
• src/main/java/gg/agit/konect/infrastructure/slack/ai/SlackEventController.java
• src/main/java/gg/agit/konect/domain/club/controller/ClubBasicApi.java

🔇 Additional comments (7)

src/main/java/gg/agit/konect/domain/club/controller/ClubBasicApi.java (1)

75-84: 권한 설명 변경이 적절해 보입니다.

[LEVEL: low]

"동아리 운영진 권한부터"로 변경된 설명이 실제 권한 검증 로직과 일치하는지 확인이 필요합니다. 에러 코드 FORBIDDEN_CLUB_MANAGER_ACCESS와 일관성이 있어 보입니다.

src/main/java/gg/agit/konect/global/config/SwaggerUiResourceController.java (1)

10-14: 내부 인프라 엔드포인트를 Swagger에서 숨기는 것이 적절합니다.

[LEVEL: low]

@Hidden 어노테이션을 사용하여 Swagger UI 리소스 제공 컨트롤러를 API 문서에서 숨기는 것은 올바른 접근입니다. 이 엔드포인트는 외부 API 소비자가 아닌 내부 인프라 용도이므로 문서 노출이 불필요합니다.

src/main/java/gg/agit/konect/infrastructure/slack/ai/SlackEventController.java (1)

18-27: Slack 이벤트 컨트롤러를 Swagger에서 숨기는 것이 적절합니다.

[LEVEL: low]

@Hidden 어노테이션 적용이 올바릅니다. Slack 웹훅 엔드포인트는 Slack 인프라에서 호출하는 내부 용도이므로 공개 API 문서에 노출될 필요가 없습니다. SwaggerUiResourceController와 동일한 패턴으로 일관성 있게 적용되었습니다.

src/main/java/gg/agit/konect/domain/club/controller/ClubMemberApi.java (3)

84-108: 복사-붙여넣기 오류 수정이 적절합니다.

[LEVEL: low]

addPreMember 엔드포인트 설명이 "조회"에서 "등록"으로 올바르게 수정되었습니다. POST 메서드의 실제 동작과 일치합니다.

---

110-121: 문서 설명이 엔드포인트 목적과 일치하도록 수정되었습니다.

[LEVEL: low]

getPreMembers 엔드포인트 설명이 "삭제"에서 "조회"로 수정되어 GET 메서드의 실제 동작과 일치합니다.

---

123-136: 권한 범위 설명이 일관성 있게 수정되었습니다.

[LEVEL: low]

removePreMember 엔드포인트의 권한 설명이 "동아리 회장 또는 부회장"에서 "동아리 운영진 권한부터"로 변경되었습니다. 에러 코드 FORBIDDEN_CLUB_MANAGER_ACCESS와 일관성이 있으며, 다른 사전 등록 관련 엔드포인트들과 동일한 권한 범위로 통일되었습니다.

src/main/java/gg/agit/konect/domain/club/controller/ClubApplicationApi.java (1)

150-158: 문서 설명이 실제 구현과 일치합니다.

ClubApply의 reject() 메서드를 확인하면 상태를 ClubApplyStatus.REJECTED로 변경하므로, "거절 시 상태를 REJECTED로 변경합니다"라는 설명이 정확합니다.

---

📝 Walkthrough

Walkthrough

Pull request는 OpenAPI 문서의 엔드포인트 설명과 권한 정보를 업데이트하고, Swagger UI에서 특정 컨트롤러를 숨기기 위한 어노테이션을 추가합니다. 런타임 로직 변경은 없으며, 모두 문서화 및 설정 조정입니다.

Changes

Cohort / File(s)	Summary
API 문서 업데이트 - 권한 및 기능 설명 src/main/java/gg/agit/konect/domain/club/controller/ClubApplicationApi.java, ClubBasicApi.java, ClubMemberApi.java	엔드포인트 설명 및 필요 권한 정보 수정. 거부 기능은 레코드 삭제가 아닌 상태 변경으로 명확화, 클럽 정보 수정 권한은 회장/부회장에서 운영진 관리자 수준으로 변경, 사전 등록 회원 관련 권한 표현 통일.
OpenAPI 문서 숨김 처리 src/main/java/gg/agit/konect/global/config/SwaggerUiResourceController.java, src/main/java/gg/agit/konect/infrastructure/slack/ai/SlackEventController.java	@hidden 어노테이션 추가로 Swagger UI 문서에서 컨트롤러 숨김 처리.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• hotfix: 동아리 지원 승인/거절 운영진 권한도 가능하도록 수정 #341: ClubApplicationApi 승인/거부 엔드포인트 설명 변경 관련
• hotfix: 동아리 승인 전 지원자 리스트 조회 페이지에서 승인된 지원자들은 안 보이게 수정 #327: ClubApplicationApi 승인/거부 관련 동작 및 문서 업데이트
• hotfix: pre-member 조회, 삭제 API 추가 #244: ClubMemberApi 사전 등록 회원 엔드포인트 정의/어노테이션 수정

Suggested labels

버그

Poem

🐰 문서를 다듬고, 권한은 명확히,
불필요한 것은 살짝 숨기니,
Swagger 페이지는 깔끔하게,
API 설명은 정확하게,
작은 변화가 모인 아름다운 조화! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	PR 제목이 변경 내용의 주요 목표를 명확하게 설명합니다. Swagger 문서와 API 구현 간의 불일치를 수정하고 엔드포인트를 숨기는 작업이 정확히 반영되어 있습니다.
Description check	✅ Passed	PR 설명이 변경 내용과 관련이 있습니다. API 문서 불일치 수정과 내부 인프라 엔드포인트 숨김 처리라는 두 가지 주요 변경 사항을 명확하게 설명하고 있습니다.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/api-docs-mismatch

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}