AWS private API Gateway 뒤에서 springdoc swagger 접근 path 관련 troubleshooting

몰랐던 점

1. private API Gateway 는 custom domain name 으로 API Mapping 연결하여 사용할 수 없다. 더 앞단에 custom domain name 으로 연결할 LB 와 TargetGroup 을 둬서 연결하는 workaround 가 있기는 하다만, 불필요하게 LB, TargetGroup 이 필요하다고 느껴졌고, 구현한 API 들의 경로는 문제가 없는데 단순히 springdoc swagger openapi 문서 제공을 위해 그런 인프라 구성을 하는 것이 매우 over engineering 이라고 생각했다.

2. spring boot + springdoc 에서 application properties 로 path, url 등을 설정할 수 있는데 해당 설정을 하면 어떻게 작동하는지 몰랐다. eg. springdoc.swagger-ui.config-url 에 값을 변경하면, configUrl 에 해당하는 리소스 자체를 저 URL 에 해당하는 곳에 생성하도록 돼있는지, 아니면 저 URL 로 접근하게 가리키도록만 돼있는지에 대해 일일이 실험하지 않고서는 파악이 어려웠다.

3. X-Forwarded-Path requeset header. spring application 이 API Gateway 와 같이 proxy 뒷단에 있는 경우, X-Forwarded-Path 헤더를 이용해서 원하는 prefix path 를 붙여줄 수가 있다. 이건 삽질 과정에서 알게된 헤더이고 삽질하면서 써보기도 했는데, 최종 결과적으로는 이 방법으로도  application properties 의 설정들 때문에 자가당착같은 상황이 생겨서 이 헤더는 사용하지 않게 됐다. 어쨌든 몰랐던 부분이었다.

 

최종적으로 선택한 모습

1. 여러가지 시도들을 많이 했지만, 최종적으로는 API GW 에서 swagger 접근만을 위한 경로에 대한 요청(resource, method, integration)을 따로 정의하는 방식으로 처리했다. 처음에는 swagger 접근만을 위한 경로의 resource, method, integration 를 설정하지 않고도 처리할 수 있는 방법을 찾기 위해 application.yml 에서 이것 저것 바꿔가며, 코드가 어떻게 동작하는지 찾아보며 해봤는데 방법을 못찾았고, X-Forwarded-Prefix 헤더도 이용해봤는데 잘 되지 않아서 차라리 지금처럼 한 것이 명시적인 방법이어서 더 낫겠다 싶어 적용하였다.

2. 그리고 API Gateway 의 stage 이름을 spring.profiles.active 값과 일치시켜두고, local 에서 개발할 때 swagger 문서 접근과 관련하여 이런 부분 신경쓰지 않아도 되게 application-local.yml 파일에서 springdoc 에서 쓰는 기본값으로 다시 덮어써주는 형식으로 처리했다.

# application.yml
springdoc:
  swagger-ui:
    disable-swagger-default-url: true
    config-url: /${spring.profiles.active}/foo/bar/v3/api-docs/swagger-config # NOTE: API GW 에서 접근 가능하게 하기 위해 /{apiGwStageName}/{prefixPath} 를 붙여줌
    url: /${spring.profiles.active}/foo/bar/v3/api-docs

# application-local.yml
springdoc:
  swagger-ui:
    config-url: /v3/api-docs/swagger-config # NOTE: local 에서는 prefix 없이 swagger-ui 에서 사용하는 default 설정을 사용하도록 덮어 씀
    url: /v3/api-docs # NOTE: local 에서는 prefix 없이 swagger-ui 에서 사용하는 default 설정을 사용하도록 덮어 씀

 

 

참고 링크 : 

https://springdoc.org/#how-can-i-deploy-springdoc-openapi-ui-behind-a-reverse-proxy

OpenAPI 3 Library for spring-boot

https://github.com/springdoc/springdoc-openapi/pull/1647

Support for Webflux springdoc behind a proxy v2.x by wiiitek · Pull Request #1647 · springdoc/springdoc-openapi