[ Spring ] Swagger 의 basic path 변경

Swagger 의 basic path 변경

사실 결과만 이야기하면 swagger의 basic path를 변경하는 방법은 그렇게 어렵지 않습니다.

implementation 'io.springfox:springfox-boot-starter:3.0.0'

기준으로

application.yml 파일에

springfox:
  documentation:
    swagger-ui:
      base-url: auth
    swagger:
      v2:
        path: auth/v2/api-docs
    open-api:
      v3:
        path: auth/v3/api-docs

해당 내용을 추가해주면 됩니다.

더 다룰 내용은 왜 path를 추가해야했나? 이다.

 

반응형

📌 Why?

현재 서비스 되고 있는 설정을 확인해보면

AWS 로드 밸런서 설정이 아래와 같이 설정되어 있다.

해당 서비스에 해당하는 path 즉 위의 예시로 /app, /auth 등을 가진 요청을 통해서만 해당 서비스에 접근하도록 설정되어있다.

그래서 단순하게 swagger를 추가했을 때의 주소인 /swagger-ui/index.html 로 접근할 수 없다.

아마 아래의 문제가 발생할 것이다.

이 정확한 이유는

swagger ui인 /swagger-ui/index.html를 만들 때, 안의 내용을 swagger에서 자체적으로 만든 /v2/api-docs api를 통해 json 형식으로 된 controller 정보를 가져오는데,

예를 들어 service.co.kr/v2/api-docs 로 요청을 보내게 되면 ALB의 path 목록에 없기에 ALB를 통과하지 못해 데이터를 못가져오는 것이다.

 

생각한 해결방안은

ui에 대한 url(기존 /swagger-ui/index.html)에 /auth 라는 path를 추가하여 /auth/swagger-ui/index.html로 접근하도록 하고,

ui가 controller에 대한 정보를 가져오는 api인 /v2/api-docs api 에도 앞에 /auth를 추가하여 /auth/v2/api-docs로 가져오게끔 수정하는 것입니다.

 

먼저 이를 해결하기 위해서 swagger 관련 클래스들이 어떤 구조로 되어있는지 파악할 필요가 있었습니다.

1️⃣ /v3/api-docs

springfox:
  documentation:
    open-api:
      v3:
        path: (값)

 

2️⃣ /v2/api-docs

springfox:
  documentation:
    swagger:
      v2:
        path: auth/v2/api-docs

각각 해당 값을 통해 지정하는 것을 확인할 수 있다.

 

또한 index.html 에 대한 설정을 확인하면

baseUrl 설정을 통해 추가할 수 있음을 볼 수 있다.

 

결국 yml 파일의 결과를 확인하면 각 도메인의 appication.yml 파일에

springfox:
  documentation:
    swagger-ui:
      base-url: auth
    swagger:
      v2:
        path: auth/v2/api-docs
    open-api:
      v3:
        path: auth/v3/api-docs

위 내용을 추가하여 swagger를 성공적으로 추가할 수 있었습니다.