스프링부트 swagger 3.0 적용시 documentationPluginsBootstrapper 오류 발생할 경우

스프링부트 2.7.15 버전에서 swagger 3.0을 적용하려고 하니 documentationPluginsBootstrapper 에러가 발생했다.

문제 발생

pom.xml 파일에 swagger 3.0 의존성 추가 

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

 

SwaggerConfig.java 파일을 생성하여 com.company.myapp 패키지를 기본 패키지로 지정하였다.

package com.company.myapp.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
       return new Docket(DocumentationType.OAS_30)
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.company.myapp"))
               .paths(PathSelectors.any())
               .build();
    }
}

이후 서버에서 아래 오류가 발생했다.

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

해결 방법

Spring boot 2.6 버전 이후에 spring.mvc.pathmatch.matching-strategy 값이 ant-apth-matcher에서 path-pattern-parser로 변경되면서 몇몇 라이브러리에서 오류가 발생하고 있다. 
따라서 application.properties 에서 swagger라이브러리 오류 방지하기 위해 직접 경로를 매칭시켜 준다.

spring.mvc.pathmatch.matching-strategy=ant-path-matcher

서버 재실행하여 아래 url로 API 사이트가 정상적으로 동작 확인하는지 확인하자.

localhost:8080/swagger-ui/index.html

또 다른 대안

springfox의 swagger 3.0이 동작하지 않는다면, springdoc-openapi-ui 라이브러리를 사용하는 방법을 추천한다. https://springdoc.org/에 따르면 springdoc-openapi-ui 라이브러리는 API 문서 생성을 자동화하는데 도움을 주며, 이 라이브러리는 다음을 지원한다.

• OpenAPI 3
• Spring-boot v3 (Java 17 & Jakarta EE 9)
• JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
• Swagger-ui
• OAuth 2
• GraalVM native images

따라서 스프링부트와 swagger-ui 간의 통합을 위해 아래 dependency를 추가하면 swagger-ui가 자동으로 배포된다.

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.2.0</version>
</dependency>

SwaggerConfig.java 파일을 별도 추가 없이도 즉시 적용 가능하며, 호출방법은 아래와 같다.

http://localhost/swagger-ui/index.html