[Swagger2] Failed to start bean 'documentationPluginsBootstrapper';

REST API 형태로 프로그램을 작성 중이라면 문서화에 Restdocs 혹은 Swagger2를 이용할 수 있다

개인적인 생각으로는 Swagger-ui가 훨씬 더 사용하기 쉽고 UI, UX가 좋지만 코드에 침투적이라는 이유 하나만으로도 싫다

다만 Restdocs를 사용해 본 경험이 있어 진행 중인 프로젝트에 학습 목적으로 Swagger2를 도입했다

 

오늘 만난 에러는 Springboot 2.6.x 이상의 버전을 사용한다면 마주칠 수 있는 문제다

난 부트 2.6.3, swagger는 3.0.0을 사용 중이다

plugins {
  id 'org.springframework.boot' version '2.6.3'
}

dependencies {
  implementation 'io.springfox:springfox-boot-starter:3.0.0'
  implementation 'io.springfox:springfox-swagger-ui:3.0.0'
}

 

국민 세팅 하에 @Bean을 이용해 컨트롤러 별 API를 나눠 실행하면 아마 아래와 같은 에러를 만날 것이다

 

 

원인은 다음과 같다

MVC path-matching 설정이 다르기 때문인데

Springfox는 Ant-based로 하고 있고 Springboot 2.6.x부터는 기본 설정이 PathPattern-based 이기 때문이다

Ant-based와 PathPattern-based의 차이점은 무엇일까?

간단히 말해 실행 시 마다 비교하느냐 미리 패턴을 컴파일 해두고 재사용하느냐 차이다

약 30~40%의 성능 차이가 난다고 하며 Spring5부터 성능 향상을 위해 기본 설정을 PathPattern으로 가져간다

 

https://stackoverflow.com/questions/70036953/springboot-2-6-0-spring-fox-3-failed-to-start-bean-documentationpluginsboot/70037507#70037507

 

 

해결법들을 찾아봤는데 아래와 같은 방법들이 있다

1. application.properties 혹은 yml에 설정 한 줄만 추가해준다

2. SwaggerConfig에서 @EnableSwagger2 대신 @EnableWebMvc를 준다

3. Swagger 대신 Springdoc을 사용한다

4. Springboot 버전을 낮춘다

 

1.

가장 추천하는 방법으로 application.yml에 설정만 추가해준다

다만 앞서 말했듯 성능 향상을 위해 PathPattern으로 맞춰놓은 것을 Ant-based로 바꾸는 것이기 때문에

사이드 프로젝트가 아닌 실무에서는 이 방법을 사용하는 건 좋지 않은 선택이다

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

https://github.com/elixir-cloud-aai/tesk-api/pull/29

 

2. 

Springboot를 사용하고 있다면 부트가 기본적인 MVC 설정을 해주기 때문에 @EnableWebMvc는 불필요하며

부트 기본 설정이 이 애노테이션이 제공하는 DelegatingWebMvcConfiguration으로 인해 변경될 수 있어 고려하지 않는다

다만 이 방법이 내가 제일 추천하는 방법 외에 제일 간편하다

SwaggerConfig 혹은 WebConfig 등에 @EnableWebMvc 붙여주면 끝난다

자세히 살펴보지는 않았으나 @EnableWebMvc를 활성화함으로써 Ant-based로 바꾸는 것으로 생각된다

 

 

3.

오픈 소스 중 하나인 springdoc을 사용하는 방식이다

최신 프로젝트가 아니라면 swagger2를 사용 중일텐데 최신 springdoc은 기본 의존성으로 swagger3을 사용하고 있고

swagger3에서는 애노테이션 변경 됐기 때문에 추가 작업이 필요하다

이 것도 최신 버전이 아닌 springdoc을 사용함으로써 해결이 가능해보인다

다만 낮은 버전의 springdoc을 쓰는 것은 임시 방편이기에 버전을 낮춰 쓸 바엔 1번 방법으로 해결하자

나는 spring-fox 대신 얘를 쓰고 있긴 한데 설정을 잘못 잡았는지 여전히 같은 문제가 나타났다

지금은 springdocs + 1번 방식으로 임시 해결 해놓은 상태다, 추후 swagger2를 또 사용할 일이 있다면 더 알아봐야겠다

 

4. 

이미 다 작성된 형태로 문서화만 붙이는 것이기에 부트 버전이 낮아지면

라이브러리 간 호환이 깨질 수 있어 버전 변경은 고려하지 않았다

버전 변경을 고려하고 있다면 2.4.x나 2.5.x로 변경하면 된다고 한다