[기타] SpringBoot 환경에서 Swagger 3.0을 적용하는 방법

오늘은 SpringBoot 환경에서 Swagger를 적용하는 방법에 관해서 알아보도록 하겠습니다.

정의

Swagger란 개발자가 REST 웹 서비스를 설계, 빌드, 테스트, 문서화하는 일을 도와주는 오픈 소스 소프트웨어 프레임워크입니다.

Spring Boot 3.0 이상 버젼에서는?

Spring Boot 3 부터는 별도의 설정 없이, 아래 의존성만 추가해주면 자동으로 설정이 완료됩니다.
설치 후, 서버 구동한 뒤, [URL]/swagger-ui/index.html에서 확인 가능합니다. 

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

Spring Boot 3.0 이하 버젼에서는?

(Gradle) Swagger 3.0 기준으로 아래 모듈을 추가해줘야 합니다.

설치방법

implementation "io.springfox:springfox-boot-starter:3.0.0"
implementation "io.springfox:springfox-swagger-ui:3.0.0"

Swagger 설정 Bean 등록하기

SwaggerConfig.java 파일을 추가하고 이를 Spring Bean으로 등록해줍니다. 

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

• Docket : Swagger 설정의 핵심이 되는 Bean 입니다.
• useDefaultResponseMessages : Swagger 에서 제공해주는 기본 응답 코드 (200, 401, 403, 404). true 로 설정하면 기본 응답 코드를 노출합니다.
• apis : api 스펙이 작성되어 있는 패키지 (Controller) 를 지정합니다.
• paths : apis 에 있는 API 중 특정 path 를 선택합니다.

application.properties 설정

Spring boot 2.6버전 이후인 경우, spring.mvc.pathmatch.matching-strategy 값이 ant_apth_matcher에서 path_pattern_parser로 변경되면서 몇몇 라이브러리(swagger포함)에 오류가 발생하므로, application.properties에 아래와 같이 설정을 추가해주면 오류가 발생하지 않습니다.

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

Controller 설정

@RestController
public class BasicController {

    @GetMapping("/api/hello1")
    public String hello1() {
        return "hello";
    }

    @GetMapping("/api/hello2")
    public String hello2(@RequestParam String param) {
        return param;
    }
}

확인 방법

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