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

[utact]

문제 원인:

• Swagger(SpringDoc)가 API 문서를 생성할 때, 컨트롤러 메서드의 파라미터를 분석하여 문서화하려고 시도합니다.
• @AuthenticationPrincipal OAuth2User principal 파라미터가 문제입니다.
• SpringDoc은 OAuth2User 인터페이스와 그 구현체들을 분석하려고 시도하다가, 내부적으로 복잡한 구조나 순환 참조 등으로 인해 직렬화 실패(StackOverflowError 등)가 발생하여 500 에러를 뱉는 경우가 많습니다.

대처 방안:

• @AuthenticationPrincipal로 주입받는 파라미터는 API 사용자가 직접 입력하는 값이 아니므로, Swagger 문서에서 숨겨야 합니다.
• @Parameter(hidden = true) 어노테이션을 붙여서 Swagger가 이 파라미터를 무시하도록 설정합니다.