!Hotfix: Swagger 인증 표시를 정리하고 공개 엔드포인트를 분리한다

[SeongHo5356]

🚀 Why - 해결하려는 문제가 무엇인가요?

• Swagger에서 토큰 입력이 실제 요청 헤더에 적용되지 않아, 인증이 필요한 API 호출이 401로 실패하는 문제가 있었습니다.
• 로그인 직후 발급된 토큰도 블랙리스트로 오판되어 인증이 막히는 현상이 있어, 원인을 추적하고 개선이 필요했습니다.

✅ What - 무엇이 변경됐나요?

• ApiDoc별 bearerAuth 적용/해제 정리
  • 보안 스키마 이름을 bearerAuth로 통일
  • 필요한 ApiDoc에만 @SecurityRequirement(name = "bearerAuth") 적용
  • 공개 API는 Swagger에서 보안 표시가 붙지 않도록 security = {} 명시
• 전역 Swagger security 제거
  • 전역 @OpenAPIDefinition.security 제거하여 불필요한 자물쇠 표시/강제 보안 적용 제거
• Redis 토큰 조회 null 처리로 인증 블랙리스트 오판 방지
  • Redis에서 키가 없을 때 "" 반환 → null 반환으로 수정하여 정상 토큰이 블랙리스트로 판정되는 문제 해결

🛠️ How - 어떻게 해결했나요?

• Swagger 인증 문제 해결

  • Swagger 보안 스키마 이름을 bearerAuth로 통일하고,
  • 실제 토큰이 헤더에 붙도록 필요한 ApiDoc에만 @SecurityRequirement(name = "bearerAuth")를 명시했습니다.
  • 전역 @OpenAPIDefinition.security를 제거해, 모든 API에 보안이 강제 적용되는 문제를 줄였습니다.
  • 공개 API(/v1/experts, /v1/experts/{expertId})는 Swagger에서 보안 표시가 붙지 않도록 security = {}로 명시했습니다.

• 블랙리스트 오판(로그아웃 토큰 체크) 해결

  • Redis 조회 로직에서 키가 없을 때 ""를 반환하던 동작 때문에,
    블랙리스트 체크가 항상 true로 평가될 수 있어 null 반환으로 수정했습니다.

• 고민/예외 사항

  • Swagger “자물쇠 표시”는 전역 설정/ApiDoc 설정이 섞이면 혼란이 커져, 전역 제거 + 필요한 곳만 명시 방식으로 정리했습니다.
  • 토큰 블랙리스트 체크는 “키 없음”과 “값 존재”를 명확히 구분하도록 반환값 정책을 통일했습니다.

💬 기타 코멘트

• 디버그 로그로 확인한 결과, Swagger에서 Authorization 헤더 자체가 붙지 않는 상태였고,
  @SecurityRequirement의 name 불일치가 원인이었습니다.
• Redis가 빈 문자열을 반환하면서 블랙리스트 판정이 항상 true가 되어 정상 토큰도 차단되는 현상이 있었습니다.
• 테스트 방법
  • Swagger UI에서 토큰 입력 후 인증 API 호출 성공 확인
  • curl로 /v1/members 호출하여 인증 성공 확인

Summary by CodeRabbit

릴리스 노트

• 새로운 기능

  • API 문서에서 인증이 필요한 엔드포인트 명시

• 버그 수정

  • 인증 토큰 검증 로직 개선 및 명확화

• 개선 사항

  • 보안 인증 표준화 (Bearer 인증 스킴 통일)
  • API 보안 설정 최적화

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

Note

.coderabbit.yaml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

⚠️ Parsing warnings (1)

Validation error: Unrecognized key(s) in object: 'tools'

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

📝 Walkthrough

Walkthrough

이 PR은 OpenAPI/Swagger 보안 문서화를 개선하고, 인증 로직을 정리하며, 보안 요구사항 이름을 통일합니다. 여러 컨트롤러와 API 문서에 bearerAuth 보안 어노테이션을 추가하고, Redis 캐시와 JWT 필터의 토큰 상태 검증 로직을 최적화합니다.

Changes

Cohort / File(s)	요약
Swagger 보안 어노테이션 추가 (bearerAuth) src/main/java/starlight/adapter/aireport/webapi/swagger/ImageApiDoc.java, src/main/java/starlight/adapter/member/auth/webapi/swagger/AuthApiDoc.java	두 개의 @Operation 어노테이션에 security = @securityrequirement(name = "bearerAuth") 추가하여 OpenAPI 명세에 베어러 인증 필수임을 명시
컨트롤러 레벨 보안 요구사항 추가 src/main/java/starlight/adapter/aireport/webapi/AiReportController.java, src/main/java/starlight/adapter/businessplan/webapi/BusinessPlanController.java	클래스 레벨에 @SecurityRequirement(name = "bearerAuth") 어노테이션 추가하여 전체 엔드포인트에 보안 메타데이터 적용
보안 어노테이션 세분화 src/main/java/starlight/adapter/expert/webapi/swagger/ExpertApiDoc.java	공개 엔드포인트(목록, 상세)에는 security = {}, 인증이 필요한 엔드포인트(AI 보고서)에는 security = @securityrequirement(name = "bearerAuth") 명시
보안 요구사항 이름 통일 src/main/java/starlight/adapter/expertApplication/webapi/swagger/ExpertApplicationApiDoc.java, src/main/java/starlight/adapter/member/webapi/swagger/MemberApiDoc.java, src/main/java/starlight/adapter/order/webapi/swagger/OrderApiDoc.java	"Bearer Authentication"에서 "bearerAuth"로 보안 요구사항 이름 변경
Swagger 설정 개선 src/main/java/starlight/bootstrap/SwaggerConfig.java	SecurityScheme(Bearer JWT)과 SecurityRequirement를 OpenAPI 정의에 추가하여 전역 보안 체계 구성
JWT 필터 토큰 검증 로직 개선 src/main/java/starlight/adapter/member/auth/security/filter/JwtFilter.java	복합 조건을 단계별 평가로 리팩토링: 토큰 존재 여부, 블랙리스트 상태, 유효성 검증을 순차적으로 검사하여 가독성 향상
Redis 캐시 동작 최적화 src/main/java/starlight/adapter/member/auth/redis/RedisKeyValueMap.java	getValue 메서드가 null 반환 (기존: 빈 문자열 반환)으로 변경하여 redis GET 호출 횟수 감소
마이너 포맷팅 src/main/java/starlight/adapter/member/auth/security/jwt/JwtTokenProvider.java	반환문을 여러 줄로 재포맷하되 로직 변경 없음
서브프로젝트 메타데이터 업데이트 (submodule commit hash)	커밋 해시 업데이트 (기능 변경 없음)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

🧵 REFACTOR, ✂️ CHORE

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7913f52 and c778979.

📒 Files selected for processing (13)

• config
• src/main/java/starlight/adapter/aireport/webapi/AiReportController.java
• src/main/java/starlight/adapter/aireport/webapi/swagger/ImageApiDoc.java
• src/main/java/starlight/adapter/businessplan/webapi/BusinessPlanController.java
• src/main/java/starlight/adapter/expert/webapi/swagger/ExpertApiDoc.java
• src/main/java/starlight/adapter/expertApplication/webapi/swagger/ExpertApplicationApiDoc.java
• src/main/java/starlight/adapter/member/auth/redis/RedisKeyValueMap.java
• src/main/java/starlight/adapter/member/auth/security/filter/JwtFilter.java
• src/main/java/starlight/adapter/member/auth/security/jwt/JwtTokenProvider.java
• src/main/java/starlight/adapter/member/auth/webapi/swagger/AuthApiDoc.java
• src/main/java/starlight/adapter/member/webapi/swagger/MemberApiDoc.java
• src/main/java/starlight/adapter/order/webapi/swagger/OrderApiDoc.java
• src/main/java/starlight/bootstrap/SwaggerConfig.java

---

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.}