[NestJS] Swagger 401 Unauthorized 에러

🤔 지 혼자 401 에러

GET /users/me/tickets API만 계속 401 Unauthorized 에러를 반환중..
분명 JwtAuthGuard로 인증 처리하고 있었고, 다른 API들은 정상적으로 작동하는데 유독 얘만 401에러 계속 뜸.

시도한 것

인증 가드(Guard) 주석 처리

가장 먼저 의심이 간 것은 인증 로직.
문제의 범위를 좁히기 위해 JwtAuthGuard를 임시로 수정하여, 실제 토큰 검증 로직을 건너뛰고 강제로 req.user에 목업(mock) 데이터를 주입하는 코드 추가.
결과는 성공 200 OK와 함께 정상적으로 데이터 반환

원인은 컨트롤러(Controller)나 서비스(Service)의 비즈니스 로직 자체에는 문제 X, 인증(Authentication) 과정에서 무언가 걸리는 것

순환 참조 문제

• 문제점: UsersModule은 인증 가드를 쓰기 위해 AuthModule을 필요로 하고, AuthModule은 유저 정보를 조회하기 위해 UsersModule을 필요로 하는 순환 참조(Circular Dependency) 관계인 상황.
  NestJS는 forwardRef를 사용해서

// 수정 전  
UsersModule,
// 수정 후
forwardRef(() => UserModule) 

이렇게 변경해봤지만 여전히 401 에러 발생 어쨌든 여기서 AuthModule 에 @Global() 데코레이터를 붙여 애플리케이션 전역에서 사용 가능하게 만듬.

혹시 몰라서 Postman으로 해봤는데

바로 성공함

• Postman: 200 OK 성공! 🎉
• Swagger UI: 401 Unauthorized 실패... 😭
  Postman은 제대로 처리했다는 것은, 서버의 인증 로직(Guard, Strategy)이 사실은 올바르게 작동, 스웨거의 문제라는 결론..

스웨거를 잘 보니

인증 가드를 걸어둔 다른 API에는 다 있던 자물쇠(🔒) 아이콘이

Users API에만 빠져 있음

@UseGuards는 서버에게 "이 API는 인증이 필요해"라고 알려주는 장치고,
스웨거를 위한 데코레이터는 @ApiBearerAuth()는 Swagger에게 "이 API 문서에 자물쇠 아이콘을 붙이고 토큰을 보내줘"라고 알려주는 장치.

확인해보니

UsersController에는 @ApiBearerAuth()가 누락되어 있어, Swagger가 인증이 필요한 API라는 사실을 인지하지 못하고 토큰을 보내주지 않았던 것
✅ UsersController에 @ApiBearerAuth() 데코레이터 한 줄을 추가하는 것으로 간단하게 해결

// users.controller.ts
@ApiTags('Users')
@Controller('users')
@ApiBearerAuth() // 👈 스웨거를 위한 데코레이터 추가
@UseGuards(JwtAuthGuard) // 👈 서버를 위한 데코레이터
export class UsersController { ... }

변수 통제: 문제가 발생할 때 다른 도구(Postman)를 사용해 테스트하는 것만으로도 문제의 원인이 서버인지 클라이언트인지 명확하게 구분할 수 있다..

아키텍처의 중요성: 모듈 간의 순환 참조는 당장은 괜찮아 보여도 예기치 못한 버그를 만들 수 있으니 AuthModule 같은 기능을 하는 모듈은 @Global()를 활용해 의존성을 단순하게 유지하는게 좋다.

코드의 실제 동작을 제어하는 로직(@UseGuards)과 문서나 도구를 위한 로직(@ApiBearerAuth)의 구분