Spring Boot 3.x에서 Swagger 사용하기: Springfox에서 SpringDoc으로 마이그레이션

결과 이미지 먼저 보기

안녕하세요! 오늘은 Spring Boot 3.x 버전에서 Swagger를 사용하는 방법에 대해 알아보겠습니다. 특히 기존에 많이 사용되던 Springfox가 Spring Boot 3.x와 호환되지 않는 문제와 이를 해결하기 위해 SpringDoc으로 마이그레이션 하는 방법을 자세히 설명하겠습니다.

문제 상황: Spring Boot 3.x와 Springfox의 비호환성

Spring Boot 3.x 버전에서 Springfox를 사용하려고 하면 다음과 같은 오류가 발생합니다:

Caused by: java.lang.ClassNotFoundException: javax.servlet.http.HttpServletRequest

이 오류가 발생하는 이유는 Spring Boot 3.x에서 Jakarta EE로 마이그레이션하면서 기존의 javax.servlet 패키지가 jakarta.servlet로 변경되었기 때문입니다. 하지만 Springfox는 아직 이 변경사항을 지원하지 않고 있어 호환성 문제가 발생합니다.

해결책: SpringDoc으로 마이그레이션

SpringDoc은 OpenAPI 3.0 사양을 지원하며 Spring Boot 3.x와 완벽하게 호환됩니다. 아래는 Springfox에서 SpringDoc으로 마이그레이션 하는 방법입니다.

1. 의존성 변경하기

기존 Springfox 의존성:

implementation 'io.springfox:springfox-swagger2:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'

 

새로운 SpringDoc 의존성:

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'  // Spring Boot 3.x용

Spring Boot 2.x 버전을 사용한다면 다음 의존성을 사용합니다:

implementation 'org.springdoc:springdoc-openapi-ui:1.6.15'

2.x 버전이라면 제 글을 안 보시고 기존 의존성 Springfox로 해도 괜찮습니다.

2. 설정 클래스 변경하기

기존 Springfox 설정:

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("sinecure.sheep.study"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("내가 처음으로 만듦")
                .description("설명 부분")
                .version("1.0")
                .build();
    }
}

 

새로운 SpringDoc 설정:

@Configuration
public class SwaggerConfiguration {

    @Bean
    public OpenAPI api() {
        return new OpenAPI()
                .info(apiInfo());
    }

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public-api")
                .packagesToScan("sinecure.sheep.study")
                .pathsToMatch("/**")
                .build();
    }

    private Info apiInfo() {
        return new Info()
                .title("내가 처음으로 만듦")
                .description("설명 부분")
                .version("1.0");
    }
}

3. 어노테이션 변경하기

컨트롤러나 모델에 사용된 Springfox 어노테이션도 SpringDoc 어노테이션으로 변경해야 합니다:

Springfox	SpringDoc
@ApiOperation	@Operation
@ApiParam	@Parameter
@ApiModel	@Schema
@ApiModelProperty	@Schema
@ApiIgnore	@Hidden
@ApiResponse	@ApiResponse

4. Swagger UI 접근하기

설정이 완료되면 다음 URL로 Swagger UI에 접근할 수 있습니다:

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

제가 설정한 포트 번호는 8080이였기에 사용하시는 포트에 맞게 변경해주시면 됩니다.

SpringDoc 설정 자세히 살펴보기

위에서 작성한 SpringDoc 설정 클래스를 좀 더 자세히 살펴보겠습니다:

@Configuration
public class SwaggerConfiguration {

    @Bean
    public OpenAPI api() {
        return new OpenAPI()
                .info(apiInfo());
    }

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public-api")
                .packagesToScan("sinecure.sheep.study")
                .pathsToMatch("/**")
                .build();
    }

    private Info apiInfo() {
        return new Info()
                .title("내가 처음으로 만듦")
                .description("설명 부분")
                .version("1.0");
    }
}

 

• OpenAPI Bean:
  • OpenAPI 객체는 API 문서의 기본 정보를 정의합니다.
  • Springfox의 Docket과 유사한 역할을 합니다.
• GroupedOpenApi Bean:
  • API를 그룹화하는 기능을 제공합니다.
  • .packagesToScan()은 Springfox의 RequestHandlerSelectors.basePackage()와 동일한 역할을 합니다.
  • .pathsToMatch()는 Springfox의 PathSelectors.any()와 동일한 역할을 합니다.
• Info 객체:
  • API 문서의 기본 정보(제목, 설명, 버전 등)를 설정합니다.
  • Springfox의 ApiInfoBuilder와 유사한 역할을 합니다.

결론

Spring Boot 3.x에서는 Springfox 대신 SpringDoc을 사용해야 합니다. SpringDoc은 OpenAPI 3.0 사양을 지원하며 Spring Boot 3.x와 완벽하게 호환됩니다. 이 글을 통해 Springfox에서 SpringDoc으로 마이그레이션 하는 방법을 알아보았습니다.

 

마이그레이션 과정은 크게 의존성 변경, 설정 클래스 변경, 어노테이션 변경 세 가지 단계로 이루어집니다. 기존에 Springfox를 사용하던 코드를 SpringDoc으로 변환하는 것은 어렵지 않으며, 비슷한 API 구조를 가지고 있어 익숙하게 사용할 수 있습니다.

 

SpringDoc을 사용하면 Spring Boot 3.x에서도 Swagger UI를 통해 API 문서를 쉽게 관리하고 테스트할 수 있습니다. 새로운 프로젝트를 시작하거나 기존 프로젝트를 Spring Boot 3.x로 업그레이드한다면 SpringDoc 사용을 적극 권장합니다!