Spring Boot 프로젝트에 Swagger 적용하기

 

 

https://velog.io/@gmlstjq123/SpringBoot-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8%EC%97%90-Swagger-UI-%EC%A0%81%EC%9A%A9%ED%95%98%EA%B8%B0

 

https://colabear754.tistory.com/99

 

 

 

ㅁ 의존성을 추가할 파일

- Gradle : build.gradle 파일에 의존성 추가.

- Maven : pom.xml 파일에 의존성 추가.

 

- 의존성을 추가한다는 것은 프로젝트에서 사용할 외부 라이브러리나 코드를 프로젝트에 포함시킨다는 의미다.

 

 

 

 

 

ㅁ 라이브러리 (Springdoc-openapi 사용)

 

- Springfox, Springdoc 라이브러리에서 Swagger UI를 제공한다.

 

- Springfox는 2020년 7월 이후로 업데이트가 중단된 반면, Springdoc은 최근까지도 지속적으로 업데이트가 되어 최근에는 Springdoc이 더 선호된다

- Spring 기반 애플리케이션에서 Swagger 문서를 생성할 때 사용하는 라이브러리에는 Springfox와 Springdoc이 있다.

최신 개발 환경에 더 적합한 것은 Springdoc이다.

 

 

 

ㅁ 현재 사용 중인 스프링 부트는 3.2.11버전이다.

Springdoc 2.0.2 버전을 사용했더니 오류가 뜬다.

Springdoc 2.6.0 버전을 사용했더니 오류가 발생하지 않았다.

 

 

 

 

ㅁ Swagger 사용을 위한 기본 설정

 

- Springdoc은 Swagger UI 설정을 하는 방법이 Springfox와 다소 차이가 있다.

- Springfox는 별도의 config 클래스에서 대부분의 설정한다.

- Springdoc는 config 클래스에서 API 문서페이지의 기본 설명만 작성하고 나머지 설정은 모두 application.properties 혹은 application.yml에서 설정한다.

또한 config 클래스에 @EnableWebMvc 어노테이션을 붙이지도 않는다.

 

 

 

 

 

ㅁ pom.xml의 의존성 목록에 라이브러리에 추가 (Maven)

 

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

 

- 추가 후 저장하고 Maven - Update Project.

- 참고로 스프링 부트 3 버전 이상일 때와 이전일 때 필요한 Springdoc 버전이 다르다.

 

 

 

 

 

ㅁ 서버 start

 

 

 

 

 

 

 

- 서버가 오류없이 구동된다.

 

 

- http://localhost:9999/swagger-ui/index.html를 입력하면 위와 같이 뜬다.

※ Swagger 3.0.0 버전부터 API Test를 위해 접속해야 하는 URL이 변경되었다.

2.x.x 버전: localhost:9999/swagger-ui.html 
3.x.x 버전: localhost:9999/swagger-ui/index.html

 

 

 

 

- SwaggerConfig 클래스를 생성해서 title, description, version을 다르게 보여지게 해본다.

 

 

 

 

 

========================================================================

 

 

 

 

 

 

ㅁ SwaggerConfig 클래스 생성

 

 

package com.br.gdcampus.config;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.models.Components;

import io.swagger.v3.oas.models.OpenAPI;

import io.swagger.v3.oas.models.info.Info;

@Configuration

public class SwaggerConfig {

  @Bean

  public OpenAPI openAPI() {

    return new OpenAPI()

        .components(new Components())

        .info(apiInfo());

  }

 

  private Info apiInfo() {

    return new Info()

        .title("Springdoc 테스트") // API의 제목

        .description("Springdoc을 사용한 Swagger UI 테스트") // API에 대한 설명

        .version("1.0.0"); // API의 버전

  }

 

}

 

 

 

- 설정 관련 클래스는 config 패키지에 둔다.

com.br.gdcampus.config 패키지에 SwaggerConfig 클래스를 만든다.

 

- 여기서 작성한 title, description, version이 Swagger UI에서 보여진다.

 

 

 

 

 

ㅁ 서버 start

 

 

 

- title, description, version이 바뀌었다.