[SpringBoot3] 스프링부트와 Swagger 연결방법

Swagger가 무엇인지, 스프링부트 애플리케이션과 Swagger의 연결 방법에 대해 작성한 글입니다.

Swagger란?

Swagger는 API 개발 및 문서화를 위한 도구입니다. Swagger를 사용하면 자동으로 API를 문서화할 수 있습니다.

 

다음 기능들을 통해서 API를 문서화하고 관리할 수 있습니다.

1. API 문서 자동 생성: Swagger를 사용하면 개발자가 작성한 API 코드를 기반으로 자동으로 API 문서를 생성할 수 있습니다. 이를 통해 API의 엔드포인트, 매개변수, 응답 형식 등에 대한 세부 정보를 쉽게 확인할 수 있습니다.
2. API 스펙 정의: Swagger는 OpenAPI Specification(OAS)을 사용하여 API 스펙을 정의합니다. 이를 통해 API의 구조와 동작 방식에 대한 명세를 명확하게 정의할 수 있습니다.
3. 클라이언트 코드 생성: Swagger를 사용하면 클라이언트 라이브러리를 자동으로 생성할 수 있습니다. 이를 통해 개발자는 클라이언트에서 API를 호출하는 데 필요한 코드를 직접 작성할 필요 없이 자동으로 생성된 코드를 사용할 수 있습니다.
4. API 버전 관리: Swagger를 사용하면 API 버전을 관리할 수 있습니다. 새로운 버전의 API를 추가하고 이전 버전과의 호환성을 유지하는 등의 작업을 쉽게 수행할 수 있습니다.

Swagger 연결하기

스펙

Spring Version: 3.2.3

Swagger: 3.0.0

 

의존성 추가하기

Gradle을 사용하는 경우, 아래 코드를 build.gradle에 추가해주세요

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

 

SwaggerConfig  파일 만들기

SwaggerConfig.java를 src > main > config 패키지에 추가해주세요

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;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

@Configuration
@EnableWebMvc
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("API Title") // API의 제목
                .description("This is my Swagger UI") // API에 대한 설명
                .version("1.0.0"); // API의 버전
    }
}

 

1. @Configuration: 이 어노테이션은 이 클래스가 Spring의 설정 클래스임을 나타냅니다. 따라서 Spring 컨테이너에 의해 빈으로 관리됩니다.
2. @EnableWebMvc: 이 어노테이션은 Spring MVC를 사용하는 애플리케이션에 필요한 설정을 활성화합니다.
3. openAPI(): 이 메서드는 OpenAPI 객체를 생성하여 설정합니다. OpenAPI 객체는 API 문서의 전체적인 구조를 나타냅니다.
   • components(new Components()): OpenAPI 객체의 구성 요소를 설정합니다. 여기서는 단순히 빈 Components 객체를 지정합니다.
   • info(apiInfo()): API 문서에 대한 정보를 설정하기 위해 apiInfo() 메서드에서 반환되는 Info 객체를 지정합니다.
4. apiInfo(): 이 메서드는 API 문서의 정보를 설정하기 위한 Info 객체를 생성합니다.
   • title("API Title"): API 문서의 제목을 설정합니다.
   • description("This is my Swagger UI"): API 문서에 대한 설명을 설정합니다.
   • version("1.0.0"): API 문서의 버전을 설정합니다.

 

Swagger UI 확인하기

프로젝트를 다시 실행한 후 http://localhost:8080/swagger-ui/index.html 에 접속하여 Swagger UI를 확인할 수 있습니다. 여기에서 API 문서를 찾고 테스트할 수 있습니다.

 

 

 

Swagger 추가 설정

지금부터는 필수적으로 설정해야 하는 것이 아닙니다!

application.properties

springdoc.swagger-ui.path=/api-docs
springdoc.swagger-ui.groups-order=DESC
springdoc.swagger-ui.tags-sorter=alpha

1. springdoc.swagger-ui.path=/api-docs
   • swagger ui 접속 경로를 localhost:8080/api-docs 로 변경함
   • /api-docs 로 접속하면 /swagger-ui/index.html로 리다이렉팅 됨
2. springdoc.swagger-ui.groups-order=DESC
   • # path, query, body, response 순으로 출력
3. springdoc.swagger-ui.tags-sorter=alpha   
   • 태그를 알파벳 순으로 정렬

Controller

@Tag 어노테이션을 추가하여 API  그룹의 이름과 설명을 지정할 수 있습니다.