Springdoc 라이브러리를 사용 이유

이전 프로젝트에는 스프링 부트 2.x 버전을 사용하면서 Springfox 라이브러리를 이용해서 Swagger를 설정하였다.

그리고 스프링 부트 3.x 버전을 사용하는 새로운 프로젝트에서 스웨거를 설정하려고 보니 SpringBoot 3.x 버전에서는 Springfox가 아닌 springdoc 라이브러리를 사용해야한다고 하는데 그 이유는,

springfox와 springdoc 두 라이브러리 모두 Spring Framework를 사용하는 애플리케이션에서 Swagger를 이용해서 API 문서화를 쉽게 할 수 있도록 도와주는 라이브러리이지만, springfox는 2020년 7월 기준으로 더 이상 업데이트가 되지 않고 있고, 그에 반해 springdoc는 꾸준히 업데이트가 되고있기에, 스프링부트 버전이 올라갈수록 springdoc를 사용해야 한다더라 그래서 springdoc를 이용해서 swagger 설정을 해보겠다.

Springdoc 라이브러리를 이용한 Swagger 설정

의존성 추가

gradle 파일에 다음과 같은 의존성을 추가하자

Swagger 사용을 위한 기본 설정

springdoc는 Swagger UI 설정을 하는 방법이 springfox와 다소 차이가 있다. springfox는 별도의 config 클래스에서 대부분의 설정을 하였지만 springdoc는 config 클래스에서 API 문서페이지의 기본 설명만 작성하고 나머지 설정은 모두 application.properties 혹은 application.yml에서 설정한다. 또한 config 클래스에 @EnableWebMvc 어노테이션을 붙이지 않아도 된다.

// Java
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("1.0.0");
    }
}

application.yml

springdoc:
  packages-to-scan: com.colabear754.springdoc_example.controllers
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    path: /
    disable-swagger-default-url: true
    display-request-duration: true
    operations-sorter: alpha

Swagger 문서에 API 등록

Springdoc도 Springfox와 마찬가지로 application 속성의 springdoc.packages-to-scan에 설정해놓은 패키지 내부의 클래스는 모두 자동으로 Swagger 문서에 등록된다. 만약 등록하고 싶지 않은 컨트롤러가 있다면 @Hidden 어노테이션을 이용하여 숨길 수 있다.

Springdoc에서는 Swagger UI를 위한 어노테이션이 변경되었다. 어노테이션 외에는 변경할 점이 없기 때문에 컨트롤러에서 어노테이션만 변경해주면 된다.

// Java
import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
 
@Tag(name = "예제 API", description = "Swagger 테스트용 API")
@RestController
@RequestMapping("/")
public class ExampleController {
    @Operation(summary = "문자열 반복", description = "파라미터로 받은 문자열을 2번 반복합니다.")
    @Parameter(name = "str", description = "2번 반복할 문자열")
    @GetMapping("/returnStr")
    public String returnStr(@RequestParam String str) {
        return str + "\n" + str;
    }
 
    @GetMapping("/example")
    public String example() {
        return "예시 API";
    }
 
    @Hidden
    @GetMapping("/ignore")
    public String ignore() {
        return "무시되는 API";
    }
}

그러면 다음과 같이 등록된 API를 볼 수 있다.