[Swagger] Spring Boot (Gradle)에서 Swagger 3.0 (Springdoc-openapi) 설정 방법

백엔드에서 만든 API를 자동으로 문서화해주는 Swagger를 프론트, 앱 팀과 협업 시 유용하게 사용했었는데요.

이번 글에서는 Swagger 3.0 (Springdoc-openapi) 설정 방법에 대해 정리하겠습니다. 👩🏻‍💻

 

Swagger란! 🤔

RESTful한 웹 서비스를 만들 때 API 문서를 자동으로 만들어주고, API를 직접 테스트할 수 있는 UI를 제공해줍니다
대표적인 라이브러리로는 Springfox Swagger, Springdoc이 존재합니다.

 

Springfox가 아닌 왜 Springdoc이냐?

-> Springfox Swagger의 경우 3.0버전을 마지막으로 업데이트가 중단되었다고 합니다. (2020년 마지막 업데이트) 그리고 Spring Boot3에서는 동작을 하지 않는 이슈도있기에,

더 최신의 많은 환경을 지원하는 (webflux도 지원) Springdoc을 선택하였습니다.

 

 

최신 버전 기준으로 Swagger를 Spring Boot 애플리케이션에 설정하는 방법 

최신 Spring Boot 버전 (Spring Boot 3)과 함께 springdoc-openapi를 사용하여 Swagger UI를 설정하는 것이 좋습니다.

springdoc-openapi는 최신 OpenAPI 3.0을 지원하며 설정이 간단합니다.

 

1. springdoc-openapi 의존성 추가

먼저, build.gradle 파일에 springdoc-openapi 의존성을 추가합니다. 최신 버전의 springdoc-openapi를 사용하도록 합니다.

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0' // 최신 버전으로 업데이트
}

 

2. Swagger 설정 클래스 작성

Swagger UI와 OpenAPI 문서를 설정하기 위한 클래스를 작성합니다. 이 클래스는 @Configuration 애너테이션을 사용하여 Spring의 설정 클래스로 지정합니다.

package com.example.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                    .title("Vennygo API")
                    .version("1.0")
                    .description("Vennygo API Description")
                    .termsOfService("http://swagger.io/terms/")
                    .license(new License().name("Apache 2.0").url("http://springdoc.org")));
    }
}

 

 

3. 예제 REST Controller 작성

Swagger 설정이 제대로 되었는지 확인하기 위해 간단한 REST Controller를 작성합니다.

package com.example.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

 

4. Spring Boot 애플리케이션 실행 및 Swagger UI 확인

Spring Boot 애플리케이션을 실행하면 Swagger UI를 통해 API 문서를 확인할 수 있습니다. 기본적으로 Swagger UI는 http://localhost:8080/swagger-ui.html 또는 http://localhost:8080/swagger-ui/index.html에서 접근할 수 있습니다.

 

5. 추가 설정 (선택 사항)

application.properties 파일에 Swagger UI 관련 추가 설정을 할 수 있습니다

# Swagger UI URL 설정
springdoc.swagger-ui.path=/swagger-ui.html

# API 문서 경로 설정
springdoc.api-docs.path=/v3/api-docs

 

 

이제 Swagger를 통해 API 문서를 확인하고, 제공된 UI를 통해 API를 테스트할 수 있습니다.

 

세부 설정 및 사용 방법은 다음 포스팅에...

https://vennycode.tistory.com/62

[Swagger] Swagger 3.0 (Springdoc-openapi) 사용 방법, 예시