Spring Boot와 Gradle을 사용하여 스웨거(Swagger)설정하기

스웨거 (Swagger)란?

• 스웨거(Swagger)는 개발자가 REST API 서비스를 설계, 빌드, 테스트, 문서화 할 수 있도록 하는 프로젝트입니다.
• 스웨거는 REST API를 문서화하는 도구입니다.
• API에 대한 명세(Spec)을 관리하기 위한 프로젝트입니다.
• API가 수정되더라도 문서가 자동으로 갱신됩니다.

 

1. 환경: Spring Boot (version 2.6.0) + Swagger2 (version 2.6.1)

2. 의존성 추가 

dependencies {
	implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.6.1'
	implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.6.1'	
}

 

Swagger 사용을 위해서는 구현체인 springfox-swagger2 가 필요하며

UI로 확인을 위해서 springfox-swagger-ui 이렇게 2개의 라이브러리가 필요합니다.

 

3. 필요 클래스파일 생성

Swagger 사용 시에는 Docket Bean 을 품고있는 설정 클래스 1개가 기본으로 필요합니다.

Spring Boot 에서는 이 기본적인 설정파일 1개로 Swagger 와 Swagger UI 를 함께 사용가능하지만,

Spring MVC 의 경우 Swagger UI 를 위한 별도의 설정이 필요합니다.
이는, Swagger UI 를 ResourceHandler 에 수동으로 등록해야 하는 작업인데,

Spring Boot 에서는 이를 자동으로 설정해주지만 Spring MVC 에서는 그렇지 않기 때문입니다.

이 별도의 설정은 따로 클래스를 생성하여 작업할 수도 있지만,

편의상 Docket Bean 을 설정 한 1개의 Swagger Config 클래스 파일에 선언, 명시하였습니다.

SwaggerConfig

• Swagger 기본 설정을 담당하는 Docket Bean 을 품고있는 클래스이며, Swagger 관련 설정은 모두 이 Bean 에 중심을 두고 있다고 합니다. 그리고 위에 언급했듯이 Spring Boot 와는 다르게 Swagger UI 의 ResourceHanlder 등록을 위해 WebMvcConfigurationSupport 클래스를 상속받은 후, addResourceHandlers 메소드를 오버라이드하여 Swagger UI 를 ResourceHandler 로 등록해주어야 합니다.
• 여기서 한 가지 체크하고 넘어가야 할 것은 ResourceHandler 등록을 위한 방법인데 2가지 방법은 아래와 같습니다.
  • @EnableWebMvc 어노테이션 설정 + WebMvcConfigurerAdapter 상속
  • WebMvcConfigurationSupport 상속

 

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@ComponentScan("com.example.demo")
public class SwaggerConfig extends WebMvcConfigurationSupport {
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false);
	}

	/** API Info */
	private ApiInfo apiInfo() {
		ApiInfo apiInfo = new ApiInfo("Swagger Sample", "APIs Sample", "Sample Doc 0.1v", "", "Author Name",
				"This sentence will be display.", "/");
		return apiInfo;
	}

	/** Swagger UI 를 Resource Handler 에 등록 */
    /////Spring Boot- 주석하면 mapping안되는 문제.../////
	/*
	 @Override public void addResourceHandlers(ResourceHandlerRegistry registry) {
	 registry.addResourceHandler("swagger-ui.html").addResourceLocations(
	"classpath:/META-INF/resources/");
	 registry.addResourceHandler("/webjars/**").addResourceLocations(
	 "classpath:/META-INF/resources/webjars/"); }
	 
}

위 소스는 Swagger 사용을 위한 기본 소스이며 아래와 같이 용도에 따라 변경하여 사용하면 된다고 합니다.

 

RequestHandlerSelectors.any() -> 전체 문서의 API 화

RequestHandlerSelectors.basePackage("com.app.api") -> 지정된 패키지만 API 화

PathSelectors.any() -> 모든 URL 패턴에 대해 수행

PathSelectors.ant("/apis/*") -> 특정 경로에 있는 컨트롤러만 포함

 

 

 

 

4. Controller에 API Info를 추가

화면에 별도의 커스텀 정보를 노출하기 위해서는 API Info를 추가해주면 됩니다.

import java.util.List;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import com.example.demo.beans.StockListVO;
import com.example.demo.services.StockListService;
import io.swagger.annotations.ApiOperation;
import lombok.RequiredArgsConstructor;

@RestController
@RequiredArgsConstructor
public class StockListController {

	private final StockListService stockListService;
	
	@GetMapping("/list")
	@ApiOperation(value = "전체 주식 조회",notes = "모든 주식을 조회")
	public List<StockListVO> stockList() {
		return stockListService.getStockList();
	}
}

위와 같이 모든 기본 설정을 끝내고 서버를 띄운 후

 http://localhost/swagger-ui.html 로 접속하게 되면 아래와 같은 화면을 볼 수 있습니다.

아무것도 클릭하지 않은 첫번째 화면에서는 본인이 설정한 패키지 or 프로젝트에 REST API 로 등록된 컨트롤러 (만약 더 있다면 n 개만큼 노출) 와 함께 API Info 로 등록해주었던 내용을 볼 수 있습니다.

 

이제 stock-list-controller를 클릭하면 StockListController에 등록된 메소드 목록이 노출됩니다.

 

선택한 Method 를 호출하였을 시 받게 되는 결과값이 예시로 나와 있으며,

하단에는 해당 Method 에서 제공하는 Parameter 정보가 파라미터명과 Type 까지 상세히 표시되고 있으며

이를 입력하여 Try it out! 으로 실제로 서비스 호출을 할 수 있습니다.

정상적으로 값을 테스트 할 수 있는 것을 확인할 수 있습니다.