Swagger UI 접근 오류

🛠️ Swagger 연동 디버깅 노트 (Spring Security + Springdoc)

지난번 Spring Security와 Swagger 연동 중 버전 이슈를 해결한 경험이 있었지만,
이번에는 추가로 Spring Security의 SecurityContext 처리 문제와
springdoc-openapi의 내부 API 충돌까지 발생하여, 전체 설정 과정을 다시 정리해 보았습니다.

---

💥 에러 요약 및 상황 설명

⚠️ 1. 인증 오류

WARN ... SecurityExceptionHandler : Authentication failed: An Authentication object was not found in the SecurityContext

이 오류는 다음 조건에서 발생합니다:

• 인증이 필요한 URL에 비인증 요청이 들어온 경우
• Spring Security가 SecurityContextHolder에서 인증 정보를 찾지 못할 경우
• 그 결과 .authenticationEntryPoint()에 등록된 SecurityExceptionHandler가 동작함

Swagger UI는 보안 필터를 우회해야 하지만, 초기 설정에서 JWT 필터에 의해 걸리며 인증이 요구되었기 때문에 이 오류가 발생했습니다.

⚠️ 2. API 문서 오류

jakarta.servlet.ServletException: Handler dispatch failed: 
java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)'

이 오류는 Swagger 문서(/v3/api-docs)를 호출했을 때 발생했으며,
결과적으로 Swagger UI에서는 다음과 같은 500 오류와 함께 동작하지 않았습니다:

Fetch error: response status is 500 /v3/api-docs

이 에러는 springdoc-openapi가 사용하는 내부 Spring API가 Spring Boot 최신 버전과 맞지 않을 때 발생합니다.

---

🔍 원인 분석

🔹 인증 문제 (SecurityContext 관련)

• Spring Security는 요청이 들어올 때마다 SecurityContext에 인증 객체(Authentication)를 저장하고 검증합니다.
• JWT 필터가 Swagger 관련 요청까지 처리하면서, 인증이 없는 상태로 필터를 통과하려 하다 보니 SecurityContext가 비어 있었고,
• 이에 따라 Authentication object was not found 예외가 발생한 것입니다.

🔹 API 충돌 문제 (springdoc-openapi 관련)

• ControllerAdviceBean.<init>(Object)는 Spring Framework 6.1 이상에서 시그니처가 변경된 생성자입니다.
• springdoc-openapi 2.5.0은 해당 변경을 반영하지 못해 NoSuchMethodError가 발생
• 즉, Spring Boot 3.5.x + Spring Framework 6.2.x 조합에는 최소 2.8.x 이상의 springdoc 사용이 필요

---

✅ 문제 해결

🔧 코드 변경 사항

1. GlobalSecurityConfig.java

   • Swagger 관련 경로(/domain/**, /swagger-ui/**, /webjars/**, /swagger-ui.html, /v3/api-docs/**)를 모두 permitAll()로 설정

2. GlobalSecurityContextFilter.java

   • shouldNotFilter() 내부에서 Swagger 관련 경로는 JWT 필터 제외 대상에 추가

3. RootController.java

   • 루트 URL (/) 요청 시 Swagger UI(/domain/api-docs.html)로 리디렉션 처리

4. springdoc 버전 업그레이드

   implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.8'

---

📂 Swagger 정상 동작 확인 경로

• /domain/api-docs.html → Swagger UI 메인
• /v3/api-docs/** → OpenAPI JSON 문서
• /swagger-ui/** → Swagger 리소스
• /webjars/** → UI CSS/JS 의존성
• / → Swagger로 리디렉션

---

📌 최종 결과

• Swagger UI 정상 접근 및 문서 로딩
• JWT 인증 필터와 충돌 없음
• SpringContext의 Security 인증 객체 문제 해결
• /v3/api-docs 500 오류 해결

---

📘 참고 및 교훈

• Spring Boot 3.x + Spring Security 사용 시 Swagger 경로는 명시적으로 예외 처리해야 함
• springdoc-openapi는 Spring 내부 API 변경에 민감하므로, 항상 공식 호환 버전 확인 필수