[JAVA] Swagger 설정 및 오류 해결

서론

swagger를 설정하면서 했던 오류를 정리하고자 한다.

 

swagger 2.X.X 설정

pom.xml

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version> 
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

build.gradle

compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

 

저의 경우는 maven으로 프로젝트를 생성하였기 때문에 pom.xml 에 해당 dependency 를 추가해줍니다. 그리고 maven update를 하면 자동으로 설정 완료!!

 

샘플 소스

@RestController
public class swaggerController {
	
	@PostMapping("/postTest")
    public ResponseEntity<?> postTest(@RequestBody ImageDto imageDto) {
        System.out.println(imageDto);
        return new ResponseEntity<>(HttpStatus.OK);
    }

    @GetMapping("/getTest")
    public String getTest() {
        return "getTest";
    }
    
    @PutMapping("/putTest")
    public ResponseEntity<?> putTest(@RequestBody ImageDto imageDto) {
        System.out.println(imageDto);
        return new ResponseEntity<>(HttpStatus.OK);
    }
    
    @DeleteMapping("/deleteTest")
    public ResponseEntity<?> deleteTest(@RequestBody ImageDto imageDto) {
        System.out.println(imageDto);
        return new ResponseEntity<>(HttpStatus.OK);
    }
}

 

swagger 테스트를 하기 위해 get / post / put / delete 4개의 rest api 를 작성하였습니다.

 

SWAGGER 접속

-- 호스트:포트/swagger-ui.html
http://localhost:9090/swagger-ui.html

제 api 포트가 9090이므로 9090포트로 접속을 시도하였습니다.

 

ERROR

1. Unable to infer base url 

Unable to infer base url. This is common when using dynamic servlet registration or when the API is behind an API Gateway. The base url is the root of where all the swagger resources are served. For e.g. if the api is available at http://example.org/api/v2/api-docs then the base url is http://example.org/api/. Please enter the location manually: 

 

갑자기 튀어나오는 알럿 문구..

 

스프링부트 프로젝트 내에 스웨거 빈을 생성하지 않아서 나온 에러입니다. 구글링하니 swaggerConfig를 생성해주면 해결이 된다고 합니다.

 

- 해결 : SwaggerConfig

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
	private ApiInfo apiInfo() {

        return new ApiInfoBuilder()
                .title("Demo")
                .description("API EXAMPLE")
                .build();
    }

    @Bean
    public Docket commonApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("example")
                .apiInfo(this.apiInfo())
                .select()
                .apis(RequestHandlerSelectors
                        .basePackage("com.example.demo.controller"))
                .paths(PathSelectors.ant("/**"))
                .build();
    }
}

apis : Swagger API 문서로 만들기 원하는 BasePackage 경로

path : URL 경로를 지정하여 해당 URL에 해당하는 요청만 Swagger API 문서로 생성. 특정 url로 제한을 걸려면 /test/** 로 넣으면 된다.

 

2. Failed to start bean 'documentationPluginsBootstrapper'

또 에러가 납니다. 구글링 해보니 Spring boot 2.6버전 이후와 swagger 2.X.X 버전과 충돌이 나는것으로 보입니다.

 

Spring boot 2.6 버전 이후는 swagger2와 충돌이 나므로 사용 X.

 

- 해결 : swagger 3.X.X 버전으로 변경

swagger 3.X.X 설정

pom.xml

<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>

build.gradle

implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '3.0.0'

버전 변경하여 다시 maven update 완료!

 

SwaggerConfig

package com.example.demo.config;

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

import com.fasterxml.classmate.TypeResolver;

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

@EnableWebMvc
@Configuration
public class SwaggerConfig extends WebMvcConfigurationSupport  {
	
	@Bean
    public Docket api(TypeResolver typeResolver) {
        return new Docket(DocumentationType.OAS_30) // 3.0 문서버전으로 세팅
                .useDefaultResponseMessages(true)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger 3.0 Api Sample")
                .description("This is Sample")
                .version("1.0")
                .build();
    }
}

 

WebConfig

package com.example.demo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
                .resourceChain(false);
    }

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/swagger-ui/")
                .setViewName("forward:/swagger-ui/index.html");
    }

}

 

SWAGGER 접속

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

제 api 포트가 9090이므로 9090포트로 접속을 시도하였습니다.

 

확인

 

정리

인터넷에 swagger 설정 정보가 대부분 2.X.X 기준으로 되어있어서 고생했는데 이렇게 정리하면서 해결하게 되었다.

프로젝트 생성한 spring boot 버전과 swagger 버전을 꼭 확인!!

 

Spring boot 2.6버전 하위 - Swagger 2.X.X (swagger2)

Spring boot 2.6버전 상위 - Swagger 3.X.X