02. SpringBoot 버전에 따른 swagger config 추가 및 시큐리티 관련 이슈

작업 과정

• 레거시 프로젝트에 API 명세화를 위해 Swagger UI를 도입하던 중 오류 발생
  • Java 11
  • SpringBoot 2.6.3

이슈 내용

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException: Cannot invoke "org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()" because "this.condition" is null

---

에러 원인

implementation 'io.springfox:springfox-boot-starter:3.0.0 의존성을 추가한 후,

스프링부트 버전2에 따른 추가 Swagger config 를 작성

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30) // OpenAPI 3.0 기반
                .select()
                .apis(RequestHandlerSelectors.any()) // API 탐색 대상 패키지 설정
                .paths(PathSelectors.any())         // 모든 경로 포함
                .build();
    }
}

해결 방법

# application.properties
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

추가 후, Springfox 버전에 따라 아래 코드를 추가 작성

// SwaggerConfig.class  
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30) // OpenAPI 3.0 기반
                .select()
                .apis(RequestHandlerSelectors.any()) // API 탐색 대상 패키지 설정
                .paths(PathSelectors.any())         // 모든 경로 포함
                .build();
    }
}

시큐리티 허용 경로 추가

// WebSecurityConfig.class
.antMatchers(
        "/swagger-ui.html",//Springfox 2.x
        "/swagger-ui/**", //Springfox 3.x , Springdoc
        "/v2/api-docs/**", //Swagger 2.x 
        "/v3/api-docs/**", //OpenAPI 3.x
        "/swagger-resources/**",
        "/webjars/**"
)

회고

• Swagger 라이브러리에 따른 접속 URL
  • SpringFox Swagger: localhost:8080/swagger-ui.html
  • SpringDoc: localhost:8080/swagger-ui/index.html

나는 Fox를 사용했는데 왜 localhost:8080/swagger-ui/index.html 로 접속이 가능한거지…

→ Springfox 3.X 에서부터 Springdoc(OpenAPI 3.x)와 유사하게 경로가 변경되었다고 한다.

정리하자면,

1. Swagger UI:
   • Springfox 2.x: /swagger-ui.html
   • Springfox 3.x: /swagger-ui/index.html (Springdoc과 동일)
2. API 문서:
   • /v2/api-docs (Swagger 2.x)
   • /v3/api-docs (OpenAPI 3.x)