swagger 설정(spring-boot, gradle)

spring-boot 버전 v2.7.x, gradle 환경에서 swagger을 적용해보자.

 

1. gradle설정 

// swagger v3 적용 사항
dependencies {
  implementation 'io.springfox:springfox-boot-starter:3.0.0'
}

// swagger v2 적용 사항
dependencies {
  implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.7.0'
  implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.7.0'
}

2. SwaggerConfig 추가

본인이 원하는 적당한 경로에 Swagger설정 클래스를 만들어 준다.

@Configuration
public class SwaggerConfig {
 @Bean
 public Docket api() {
   return new Docket(DocumentationType.OAS_30)
                        .apiInfo(apiInfo())
                        .select()
                        .apis(RequestHandlerSelectors.any())	// 특정 패키지경로 추적. 1차 필터
                        .paths(PathSelectors.regex("/api.*"))	// 위의 apis중에서 특정 path조건 API만 문서화. 2차 필터
                        .build()
                        .groupName("API 1.0.0")
                        .securitySchemes(Arrays.asList(apiKey()))
                        .securityContexts(Arrays.asList(securityContext()));
 }

 private ApiKey apiKey() {
   return new ApiKey("apiKey", "Authorization", "header");
 }
	
 private SecurityContext securityContext() {
   return SecurityContext.builder()
            .securityReferences(defaultAuth())
            .operationSelector(o -> PathSelectors.regex("/api.*").test(o.requestMappingPattern()))
            .build();
 }
	
 private List<SecurityReference> defaultAuth() {
   AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
   AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
   authorizationScopes[0] = authorizationScope;
   
   return Arrays.asList(new SecurityReference("apiKey", authorizationScopes));
 }
	
 private ApiInfo apiInfo() {
  return new ApiInfoBuilder()
               .title("test Spring boot REST API")
               .version("1.0.0")
               .description("SWAGGER")
               .build();
  }
}

 

서버 구동했을때

Failed to start bean 'documentationPluginsBootstrapper' 라는 에러가 뜨는 경우

 

해결법

Spring Boot 2.6.0 이상부터 요청 경로를 ControllerHandler에 매칭시키기 위한 전략 기본값이ant-path-matcher에서 ant-path-pattern-parserfh로 변경 되었기 때문.

application.yml 파일에 아래와 같이 추가해주면 된다.

//application.yml
spring:
  mvc:
    pathmatch:
      matching-strategy: ant-path-matcher

 

결과

http://localhost:8080/swagger-ui/ 로 접속하면 아래와 같이 나온다

swagger v2.0 버전을 사용하면 http://localhost:8080/swagger-ui.html로 접속