Springboot 3.x에 Swagger 사용해보기

현재까지 Springboot 2.x 만 사용을 해오다가 새로운 프로젝트를 하게 됐는데 팀원 분이 3.x를 사용해봤다고 하여 경험 삼아 사용해보기로 했다. 또 사용해보지 않았지만 최근 많이들 사용하는 기술을 사용해보자 했는데 그 중 하나가 swagger였다. swagger를 적용시켜보기 위해서 test 파일을 만들어 적용을 시켜보는데 역시나 많은 에러들을 만났다.

 

첫번째 시도 (실패)

 

먼저 해당 종속성을 추가하고 config와 controller를 작성했다.

dependencies {
	
	implementation 'io.springfox:springfox-swagger2:3.0.0'
	implementation 'io.springfox:springfox-swagger-ui:3.0.0'
    
}

@Configuration
public class SwaggerConfig {
  
  private static final String API_NAME = "Swagger Test API";
  private static final String API_VERSION = "0.0.1";
  private static final String API_DESCRIPTION = "이것은 스웨거 테스트입니다.";

  @Bean
  public Docket api() {
      return new Docket(DocumentationType.SWAGGER_2)
      		  .useDefaultResponseMessages(false) //기본 응답코드 표시
              .apiInfo(apiInfo()) //Api 정보
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.test.swaggerTest")) //적용할 패키지명
              .paths(PathSelectors.any()) //패키지 하위에서 적용할 url path 지정
              .build();
  }
	
  public ApiInfo apiInfo() {
    return new ApiInfoBuilder()
      .title(API_NAME)
      .version(API_VERSION)
      .description(API_DESCRIPTION)
      .build();
  }
}

@RestController
public class TestController {

    @GetMapping
    @ApiOperation(value="테스트", notes="테스트 중입니다.")
    public ResponseEntity Test(TestDto dto) {

        return new ResponseEntity<>(HttpStatus.OK);
    }
}

@Getter
@AllArgsConstructor
public class TestDto {

    private String name;
}

 

해당 코드 작성 후에 실행을 해봤는데 결과는... 실패

 

알고 보니

Swagger 2.x.x까지는 localhost:8080/swagger-ui.html이였지만.
Swagger 3.0.0부터는 localhost:8080/swagger-ui/index.html로 변경되었기 때문에 이 부분 신경 써서 접속하면 된다.

 

그리하여 다시 접속을 해봤는데 

결과는 Whitelabel Error.

 

 

이후에 에너테이션을 붙여야한다는 글을 보고

 

두번째 시도(실패)

@Configuration + @EnableSwagger2을 붙여보았다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {
  
  private static final String API_NAME = "Swagger Test API";
  private static final String API_VERSION = "0.0.1";
  private static final String API_DESCRIPTION = "이것은 스웨거 테스트입니다.";

  @Bean
  public Docket api() {
      return new Docket(DocumentationType.SWAGGER_2)
      		  .useDefaultResponseMessages(false) //기본 응답코드 표시
              .apiInfo(apiInfo()) //Api 정보
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.test.swaggerTest")) //적용할 패키지명
              .paths(PathSelectors.any()) //패키지 하위에서 적용할 url path 지정
              .build();
  }
	
  public ApiInfo apiInfo() {
    return new ApiInfoBuilder()
      .title(API_NAME)
      .version(API_VERSION)
      .description(API_DESCRIPTION)
      .build();
  }
}

해당 에너테이션을 추가했는데 결과는 에러..

 

에러 사진을 캡처를 못했지만 spring mvc 패턴과 관련된 에러가 나타났다. 글을 찾아보니 swagger config를 사용하다보니 뭔가 spring mvc패턴을 건드려서 생긴 에러 같다. 

 

해결방법은? yml파일에 해당 코드를 추가하는 것이었다.

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

추가하고 실행한 결과는?

후.. 역시나 마찬가지의 결과 이쯤되면 정신이 나갈거 같았다..

 

세번째 시도(성공)

spring 3.x 이후로는 springfox 대신 springdoc를 사용하라는 글을 찾게 되었다..

 

공식 문서 : https://springdoc.org

 

그 전 springfox 종속성 두개를 지우고 해당 종속성을 추가했다.

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

그리고 자연스럽게 swaggerconfig 코드는 필요가 없어져서 삭제를 했고 

 

@RestController
public class TestController {

    @GetMapping
    public ResponseEntity Test(TestDto dto) {

        return new ResponseEntity<>(HttpStatus.OK);
    }
}

@Getter
@AllArgsConstructor
public class TestDto {

    private String name;
}

위의 코드만을 남겼다. 컨트롤러 단에 추가적으로 작성했었던 에너테이션도 삭제를 해주었다.

 

그리고 실행을 했더니..!!

 

결과는 성공...ㅠㅠ

 

따로 에너테이션을 설정해주지 않아도 controller단의 메서드를 자동으로 인식해서 나오는 것 같다. 이전 버전보다 조금 더 사용하기 편리해진 느낌이다. 

 

하지만 이전 버전에서 에너테이션을 사용해 부가 설명을 수정할 수 있는 방법은 아직 잘 모르겠다. 공식문서를 이용해서 공부를 해봐야할 것 같다. 

 

아 그리고 첫번째와 두번째 시도에서 사용한 방법은 아마 spring 2.x 버전에서는 사용 가능한 방법일 것이다. 혹시나 2.x버전을 사용하시는 분이라면 참고하면 좋을 것 같다.