[Spring / TIL] SpringBoot 버전 3.X.X에 Swagger적용하기

프로젝트 진행 중 클라이언트와의 협업에 필요한 API명세를 위해 Swagger를 도입하게 되었습니다.

 

이 글은 SpringBoot 버전 3.0.0 이상을 사용하는 프로젝트에서 Swagger를 도입할 때 사용해야 하는 Swagger 라이브러리에 대해 정리해보려고 합니다.

 

결론부터 말씀드리자면.

 

0. SpringBoot 3.0.0 이상부터는 springfox가 아닌 springdoc-openapi-ui 라이브러리를 사용해야 합니다.

 

아니 웬만하면 springdoc-openapi-ui를 사용하는 편이 좋습니다. SpringBoot3.0.0 이상이 아니라도 말이죠.

 

검색해 보면 상위 게시물들은 물론 거의 대부분의 게시물에서 springfox를 이용한 swagger 설정방법을 설명해주고 있지만 사실 sprinddoc-openapi를 써야 합니다.

 

springfox와 springdoc 두 라이브러리 모두 Spring Framework를 사용하는 애플리케이션에서 Swagger를 이용해서 API 문서화를 쉽게 할 수 있도록 도와주는 라이브러리입니다.

 

그렇다면 왜 springdoc-openapi-ui를 사용하는 편이 좋을까요? 두 라이브러리의 깃헙을 들어가 봤습니다.

 

spinrgfox Github

springfox-github

springfox는 2020년 7월 14일 기준으로 더 이상 업데이트가 되지 않고 있습니다.

 

springdoc-openapi

 

springdoc-openapi-github

 

그에 반해 springdoc-openapi는 2022년 12월 16에 마지막 릴리즈가 있네요. 계속해서 업데이트를 하고 있다는 증거이고, SpringBoot 버전이 올라갈수록 더더욱 springdoc-openapi를 사용해야 할 듯합니다.

 

1. springdoc을 사용한 Swagger적용(Gradle, yml 기반으로 적용)

 

Swagger OpenAPI3.0에 대해서 간단하게 정리하자면 

 

springdoc 라이브러리가 OpenAPI3.0 스펙에 맞는 JSON을 만들어주면, Swagger UI가 화면을 만들어서 JSON들을 띄워주는 역할을 합니다.

 

springdoc-openapi-ui를 살펴보면 swagger-ui를 포함하고 있는 것을 확인할 수 있습니다.

• swagger-ui : 핵심 로직 구현
• springdoc-openapi : swagger-ui를 추상화해서 더 잘 활용할 수 있게 해주는 라이브러리

 

1-1. build.gradle에 dependency추가

 

https://springdoc.org/v2/ 공식문서에서 제공하는 dependency로 설치를 했습니다.

 

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

springdoc.org/v2/

 

1-2. Swagger 문서 확인

 

이후 http://localhost:8080/swagger-ui/index.html 에 접속하게 되면 아래와 같이 API 문서를 확인할 수 있습니다.

 

swagger 화면

 

2. 이외에 옵션들

 

기본 옵션 말고도 SwaggerConfig라는 java파일 안에 설정을 하는 방법도 있습니다.

 

package com.couple.love.config;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import lombok.RequiredArgsConstructor;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
        info = @Info(title = "Couple App",
                description = "couple app api명세",
                version = "v1"))
@RequiredArgsConstructor
@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi chatOpenApi() {
        String[] paths = {"/v1/**"};

        return GroupedOpenApi.builder()
                .group("COUPLE API v1")
                .pathsToMatch(paths)
                .build();
    }
}

 

위와 같이 Config를 설정해 주면 수동으로 명세를 적용할 수 있습니다. 더 자세하게 말이죠. 

 

하지만 컨트롤러에도 하나하나 적용을 해줘야 하는 단점이 생기긴 하지만 더 잘 쓰기 위해서 알아두면 좋을 듯합니다.

 

 

3. 정리

 

이번 게시물은 제가 했던 실수를 다른 분들이 반복하지 않았으면 하는 마음에 간단하게 정리해 봤습니다.

라이브러리를 사용할 때에는 무지성으로 사용하지 않고 현재 버전에 맞는지, 아니면 왜 이 라이브러리를 사용해야 하는지 꼼꼼하게 따져보는 습관을 가져야겠습니다.

 

감사합니다.