[SpringBoot] Swagger 사용 시 오류

📌환경

IntelliJ Ultimate

Java 17

 

Spring boot 3.2.3

Gradle - Groovy

Dependencies: 

Spring Web

Thymeleaf

Spring Data JPA

lombok

MariaDB 10.11

Spring Dev tool

 

📌문제

Swagger Configuration 작성 시 기존에 사용하던 정적 리소스 내 모든 파일이 인식되지 못함(No mapping GET...), swagger-ui/index.html가 404로 뜨는 문제가 발생하여 글을 작성한다.

 

 

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

 

 

의존성 추가 시에는 아무런 문제가 발생하지 않는다. 다만 localhost:8080/swagger-ui/index.html로 접속하면 404가 떴다.

 

 

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

 

 

여기서 `SwaggerConfig`와 `CustomServletConfig`를 작성하면 해당 페이지의 접속 문제는 해결된다.

 

 

import springfox.documentation.api.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

	@Bean
    public Docket api(){
    
    	return new Docket(DocumentationType.OAS_30)
            .useDefaultResponseMessages(false)
            .select()
            .apis(RequestHandlerSelectors.basePackage("org.zerock.b01.controller"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
    }
    
    private ApiInfo apiInfo() {
    	return new ApiInfoBuilder()
            .title("Boot 01 Project Swagger")
            .build();
    }

 

 

package org.zerock.b02.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
@EnableWebMvc
public class CustomServletConfig extends WebMvcConfigurationSupport {

}

 

 

 

 

 

 

됐당! 하고 신나게 돌아서는 순간 다른 페이지에서 기존에 적용했던 CSS가 모두 박살나는 것을 목격할 수 있다.

 

집에 있는데 집에 가고 싶음

 

 

 

Swagger UI가 적용되면서 정적 파일의 경로가 달라졌기 때문이다.

서치한 대로 `@EnableWebMVC`를 지우면 swagger-ui/index.html이 접속되지 않고, 넣으면 CSS가 박살났다. 둘이 사이좋게 지냈으면 좋겟는디

 

찾아보니 `build.gradle`에 의존성으로 추가한 springfox가 스프링 부트 3.0 이상에 사용할 시 오류가 발생한다는 사실을 발견했다. 

 

 

📌해결

내 문제가 아니라 스프링 부트 + springfox의 충돌 문제인 것 같으니 springfox에서 springdoc으로 종속성을 변경해준다.

springfox와 springdoc은 둘 다 Swagger를 사용할 수 있도록 도와주는 라이브러리다. springfox는 2020년 이후로 업데이트를 중단했고, springdoc은 2019년에 처음 나왔다. 글을 작성하는 현재 2024년 3월 시점 3개월 전인 2023년 12월에도 최근 업데이트 되었다.

 

 

dependencies {
	...
    
//	swagger	
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
}

 

 

 

springdoc에 맞추어 `SwaggerConfig`를 변경하고,`CustomServletConfig`는 삭제해준다.

 

 

package org.zerock.b02.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

        @Bean
        public OpenAPI openAPI() {
            return new OpenAPI()
                    .components(new Components())
                    .info(apiInfo());
        }

        private Info apiInfo() {
            return new Info()
                    .title("Springdoc 테스트")
                    .description("Springdoc을 사용한 Swagger UI 테스트")
                    .version("2.2.0");
        }
    }

 

 

 

 

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

 

 

 

 

 

swagger-ui/index.html도 잘 나오고, 정적 리소스 파일도 모두 잘 매핑된 것을 확인할 수 있다!

 

 

📌 springdoc은 어떻게 써요

[Spring] 스프링 부트 3.2.3에서 Swagger(springdoc) 사용하기!

 

 

📌참고

[Springdoc] No mapping for GET /swagger-ui/index.html 오류 조치