스프링부트 3.X에 Swagger 적용하기

 

프로젝트 개발에 본격적으로 들어가기에 앞서 API 문서 자동화가 필요한 거 같아 Swagger를 적용하려한다.

Swagger란?

스웨거는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. 별도의 스웨거 UI 도구를 통해 스웨거를 사용하며 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.
출처 : 위키백과

 

반응형

 

Springfox Swagger  vs  Springdoc

Spring Swagger의 경우 2020년의 마지막 버전인 3.0.0에서 멈춰있고, Springdoc의 경우엔 2023년에도 업데이트가 된 것을 mavenRepository에서 확인할 수 있다. 또한 둘의 차이점은 webflux의 지원 여부가 있다. springfox의 경우 webflux를 지원하지 않으며, springdoc의 경우엔 webflux를 지원한다.

 

스프링부트 3.X에 Springfox Swagger를 적용해본 결과 'Whitelable Error Page' 에러가 발생하여 최신 버전인 Springdoc를 적용했다.

 

반응형

 

build.gradle

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

위 종속성을 추가해주면 된다. 추가 후 로드하고 아래 주소로 접속하면 swagger UI 화면을 볼 수 있다.

 

 

Config 파일 구성

/**
 * Swagger springdoc-ui 구성 파일
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .title("~~ API Document")
                .version("v0.1")
                .description("~~ 프로젝트 API 명세서");
        return new OpenAPI()
                .components(new Components())
                .info(info);
    }
}

 

반응형

 

application.yml 설정

# Swagger springdoc-ui configuration
springdoc:
  packages-to-scan: com.kr.~~ # 프로젝트 패키지 경로
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    path : ~~-api.html # localhost:8080/~~-api.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /api-docs/json
    groups:
      enabled: true
    cache:
      disabled: true

 

 

http://localhost:8080/~~-api.html을 주소창에 입력하면 자동으로 http://localhost:8080/swagger-ui/index.html로 접속된다.