[Spring Boot] Swagger 3.0.0 적용하기

 

Spring Boot 2.7.5, Swagger 3.0.0 바탕으로 진행하였습니다. 

 

 

◎ Swagger

Swagger는 웹 서비스(API)를 설계, 빌드 및 문서화하기 위해 사용되는 도구 및 프레임워크입니다.

API는 응용 프로그램과 다른 소프트웨어 컴포넌트 간의 통신을 위한 인터페이스로, 클라이언트가 서버에 요청을 보내고 서버는 해당 요청에 대한 응답을 반환합니다. Swagger는 이러한 API를 설계하고 문서화하기 위한 기능을 제공합니다.

 

Swagger는 주로 RESTful API를 설계하는데 사용되며, API의 엔드포인트, 매개변수, 요청 및 응답 형식, 인증 방식 등을 정의할 수 있습니다. 또한 Swagger를 통해 API를 문서화하고 테스트하는 과정에서 발생하는 오류와 버그를 조기에 발견하고 수정할 수 있습니다. 따라서 Swagger는 개발자들이 효율적으로 API를 개발하고 관리할 수 있는 강력한 도구입니다.

 

 

◎ Swagger 적용하는 방법

 

1. 의존성을 추가한다. 

Maven으로 빌드한 경우 pom.xml 파일에 의존성을 추가해준다. 

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

 

 

Gradle로 빌드한 경우 build.gradle 파일에 의존성을 추가해준다. 

dependencies {
	...
    implementation 'io.springfox:springfox-boot-starter:3.0.0'
    implementation 'io.springfox:springfox-swagger-ui:3.0.0'
    ...
}

 

 

2. Configuration 이름의 패키지를 생성한 후 Class를 만들어 코드를 작성한다. 

@Configuration
public class SwaggerConfiguration {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.any()) //RequestMapping으로 할당된 모든 API
                .paths(PathSelectors.any()) //모든 URL
                .build();
    }
}

 

 

SwaggerConfiguration 클래스의 자세한 설정은 아래와 같다.

 

• Docket : Springfox 프레임워크의 api 들에 대한 기본 인터페이스 설정을 위한 빌더이다. Swagger 의 기본 설정을 위한 Bean 으로 사용된다.
• select() : 선택된 api 에 대한 빌더를 초기화한다.
• apis() : Swagger API 문서로 만들기 API 메서드들이 작성되어 있는 패키지 (Controller 를 포함하고 있는 패키지) 의 경로를 지정해준다.
• paths() : 특정 Path 를 지정하여 apis() 에 지정된 경로 중에서 원하는 경로의 api 만 문서화한다.
• build() : ApiSelectorBuilder 를 빌드한다. Docket 타입을 반환한다.

 

 

3. 에러가 뜬다면 application.properties를 application.yml로 변경한 후 아래 코드를 추가한다.

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

Springboot 2.6.x 버전과 Swagger3.x.x 버전 간 호환 이슈가 있다고 한다. 따라서 config파일에 해당 내용을 기입해야한다.

 

 

 

4. 주소로 접속한다. 

Swagger는 서버를 실행시킨 뒤, http://localhost:8080/swagger-ui/ 혹은  http://localhost:8080//swagger-ui/index.html 에서 확인할 수 있다.

사이트에서 프로젝트의 모든 API를 볼 수 있고 API request, response 테스트도 해볼 수 있다.