[SpringBoot] SpringBoot3에서 Swagger3 적용기

발단

사이드 프로젝트 개발 중 swagger 세팅 중에 에러가 발생했습니다. 이의 대해서 알아보고 정상적으로 동작하기 위해 어떤 설정이 필요한지 정리했습니다.

 

1. 기존에 설정되어 있는 dependency

build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.0.1'
}

dependencies {
    // https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
    implementation group: 'io.springfox', name: 'springfox-swagger2', version: '3.0.0'
    implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
}

 

SwaggerConfig 설정

@Configuration
@EnableSwagger2
public class SwaggerConfig{

	@Bean
    public Docket api() {
        return (new Docket(DocumentationType.SWAGGER_2))
        .host(this.customProperties.getSwaggerUrl())
        .select()
        .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
        .paths(PathSelectors.ant("/**"))
        .build();
    }

}

 

2. 설정 후 application 실행시 에러 발생

java.lang.TypeNotPresentException: Type javax.servlet.http.HttpServletRequest not present

해당 현상에 대해서 알아보니 springfox에서 해당 이슈가 open되어 있었습니다.

 

https://github.com/springfox/springfox/issues/3983

How to run with spring boot 3.0.0-snapshot? · Issue #3983 · springfox/springfox

현재 swagger를 제공해주는 Springfox에서 SpringBoot 3.0.x 버전대에서는 이슈가 발생하는 것으로 나와있습니다.

 

발생현상에 대해서 보면 SpringBoot3에서는 이제 javax가 아닌 jakarta를 사용하고 있는데, Swagger에서는 아직 javax를 사용하고 있어서 생기는 문제로 나와있습니다.

 

3. 해결방안

springdoc-openapi를 사용하면 위의 문제가 바로 해결됩니다. Swagger에서 자세한 설정을 하지 않는 이상 SwaggerConfig도 설정없이 바로 사용가능합니다.

 

buil.gradle 추가

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

 

https://springdoc.org/v2/#Introduction

springdoc-openapi v2.1.0

 

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

GitHub - springdoc/springdoc-openapi: Library for OpenAPI 3 with spring-boot

github에서 더욱 간략하고 빠르게 설정하는 방법이 README.md파일에 나와있어서 바로 적용해봐도 좋을 것 같습니다.