[Project] Gateway를 통한 Swagger 문서 라우팅 정리

개요

처음 목표는 단순했다.
gateway를 통해 내부 서비스의 API 문서를 확인할 수 있게 만드는 것이었다.

처음에는 Swagger UI 설정만 맞추면 될 줄 알았다.
하지만 로그를 보니 문제는 문서 설정 하나가 아니라, 외부 요청 경로와 내부 서비스 경로가 다르게 해석되는 것에 있었다.

문제

외부에서는 gateway를 통해 prefix가 붙은 경로로 접근한다.

/auth/v3/api-docs

하지만 내부 서비스는 prefix 없이 동작한다.

/v3/api-docs

즉 gateway가 외부 prefix를 제거해서 내부 서비스로 넘겨야 했다.
내가 헷갈렸던 지점도 바로 이 부분이었다.

외부에서 보는 주소와 내부 서비스가 실제로 받는 주소가 다르다는 점을 놓치면, 설정을 계속 바꿔도 같은 문제가 반복된다.

시도

처음에는 YAML 설정의 StripPrefix를 조정하며 해결하려 했다.
하지만 실행 환경에서 기대대로 동작하지 않았고, 실제 요청이 어떤 경로로 전달되는지 로그를 계속 확인해야 했다.

이 과정에서 401, 404, 302를 계속 마주쳤다.
처음에는 모두 비슷한 실패처럼 보였지만 의미가 달랐다.

401: 인증 또는 보안 필터에서 막힘
404: 내부 서비스가 해당 경로를 모름
302: 문서 경로 redirect

결국 단순히 “문서가 안 열린다”라고 볼 것이 아니라, 요청이 어느 계층에서 어떻게 바뀌고 있는지 나누어 봐야 했다.

정리

최종적으로는 gateway 라우팅을 코드로 고정했다.
설정 파일만으로도 처리할 수 있는 문제라고 생각했지만, 지금 구조에서는 코드로 명시하는 쪽이 더 확실했다.

이번 작업을 하며 가장 크게 느낀 점은 gateway가 붙으면 경로가 두 개가 된다는 것이다.

외부 클라이언트가 보는 경로
내부 서비스가 실제로 받는 경로

이 둘을 구분하지 않으면 로그를 봐도 문제를 잘못 해석하게 된다.
앞으로 gateway를 통해 문서나 API를 연결할 때는 먼저 이 경로 차이부터 확인해야겠다.