Swagger가 기본 페이지로 열릴 때? 프록시 설정으로 바로잡기

안녕하세요 makeviibe 입니다.

최근 EC2 환경에서 프론트엔드(React)와 백엔드(Spring Boot + Kotlin)를 하나의 서버에 배포했습니다.

Nginx를 통해 모든 요청을 받아 프론트/백엔드로 라우팅하는 구조였는데,

배포 후 Swagger 페이지에 접속했을 때 예상과 다른 화면이 열렸습니다.

---

🐛 문제 상황

Swagger는 백엔드에서 /v3/api-docs/ 또는 /swagger-ui.html 경로를 통해 접근합니다.

하지만 실제 브라우저에서 해당 주소로 접속했을 때,

Swagger UI가 아닌, 프론트엔드(React)의 기본 페이지(index.html) 가 열렸습니다.

즉, Swagger 요청이 백엔드가 아닌 프론트엔드 정적 파일로 전달된 것이었습니다.

---

🔍 원인

Nginx 설정에서 모든 경로를 React 앱으로 프록시하고 있었고,

예외 경로를 별도로 지정하지 않았기 때문입니다.

위 설정은 존재하지 않는 모든 경로를 index.html로 리다이렉트하기 때문에

Swagger 요청 역시 React 앱이 처리하게 되었던 것이죠.

---

🛠 해결 방법 – Swagger 전용 프록시 설정 추가

Swagger 경로(/v3/api-docs/, /swagger-ui.html)만 백엔드로 직접 전달하도록 설정했습니다:

• Swagger 관련 요청만 명시적으로 백엔드로 프록시
• 그 외 요청은 기존대로 프론트로 전달

---

✅ 적용 결과

이제 /swagger-ui.html 접속 시

정상적으로 Spring Boot에서 제공하는 Swagger UI가 표시되고,

프론트와 백엔드가 하나의 서버에서 안정적으로 분리되어 동작하게 되었습니다.

---

💡 팁

Spring Boot + Swagger(OpenAPI 3)를 사용할 경우 기본 엔드포인트는 다음과 같습니다:

• API 명세: /v3/api-docs
• Swagger UI: /swagger-ui.html
• 또는 /swagger-ui/index.html (버전에 따라 다름)