4.5 Swagger

1) Swagger 개요

1. 스웨거(Swagger)란?

스웨거는 Web API 문서화를 위한 도구입니다.

스웨거 홈페이지(https://swagger.io)에서는 스웨거를 OAS(Open API Specification)이라고 소개하고 있습니다.

말그대로 API들이 가지는 명세(Spec)을 관리하기 위한 프로젝트라고 말할 수 있습니다.

Web API를 수동으로 문서화 하는 것은 굉장히 힘든 작업입니다.

Web API의 스펙이 변경되었을 때 문서 역시 변경이 되야 하는데 이를 유지하는 것이 쉽지가 않습니다.

 

Swagger를 사용하면 Web API가 수정되더라도 상관 없습니다. 문서가 자동으로 갱신이 되기 때문입니다.

2. 스웨거의 기능

스웨거 홈페이지를 가보면 아래와 같은 기능이 있습니다.

 

1) API Design

2) API Development

3) API Documentation

4) API Testing

5) API Mocking and Virtualization

6) API Governance

7) API Monitoring

8) OpenAPI & Swagger

 

Web API를 만드는 개발자와 Web API를 이용하는 개발자가 있다고 생각해 보겠습니다.

Web API를 이용하는 개발자는 Web API가 만들어질 때까지 기다린다면 작업이 상당히 느려질 수 있을 것입니다.

Web API를 만드는 사람과 Web API를 사용하는 사람 간에 미리 명세를 정의하고 공유할 수 있다면

개발이 상당히 편리해 질 것입니다.

지금 이야기 한 것들을 편하게 해주는 도구 중에 하나가 ‘스웨거’라고 말할 수 있습니다.

3. 스웨거 허브를 이용하여 API를 명세화 하고 테스트하기

스웨거 허브 사이트를 이용하면 Web API를 만들지 않더라도 Web API를 명세화할 수 있습니다.

또한, Web API를 명세화만 하는게 아니라 간단히 테스트도 할 수 있다는 장점을 가지고 있습니다.

---

2) Swagger 설정하기

코드링크: calculator06

1. pom.xml 파일 수정

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.6.1</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.6.1</version>
</dependency>

2. WebAppInitializer 클래스 작성하기

자바 웹 어플리케이션을 만들 때는 web.xml 파일이나 WebApplicationInitializer를 구현한 클래스를 만들거나 해야 한다고 앞에서 설명했었습니다. (Spring MVC를 이용한 웹 페이지 작성 실습 참고)

앞에서 설명한 WebApplicationInitializer를 앞에서는 직접 구현했었는데

이번에는 WebApplicationInitializer를 구현하고 있는 AbstractAnnotationConfigDispatcherServletInitializer를

상속받아 작성해 보도록 하겠습니다.

AbstractAnnotationConfigDispatcherServletInitializer 클래스는 WebApplicationInitializer를 구현하고 있으면서

필요한 부분만 오버라이딩 하여 구현하도록 제공하는 클래스입니다.

 

WebApplicationInitializer.java

package org.edwith.webbe.calculator.config;

import org.springframework.web.filter.CharacterEncodingFilter;
import org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer;

import javax.servlet.*;

public class WebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {

	// Spring 기본 설정파일 클래스를 지정합니다.
// 여러분은 ApplicationConfig.class를 작성해줘야 합니다.
	@Override
	protected Class<?>[] getRootConfigClasses() {
		return new Class<?>[] { ApplicationConfig.class };
	}

	// Spring MVC 설정 파일 클래스를 지정합니다.
	// 여러분은 MvcConfig.class를 작성해줘야 합니다.
	@Override
	protected Class<?>[] getServletConfigClasses() {
		return new Class<?>[] { MvcConfig.class };
	}

	/*
	 * DispatcherServlet이 동작할 맵핑정보를 설정합니다. "/"를 설정한다는 것은 모든 요청을 DispatcherServlet이
	 * 처리한다는 것을 의미합니다.
	 */
	@Override
	protected String[] getServletMappings() {
		return new String[] { "/" };
	}

	/*
	 * 필터를 설정합니다. 여기에서는 인코딩 필터를 설정하고 있습니다.
	 */
	@Override
	protected Filter[] getServletFilters() {
		CharacterEncodingFilter encodingFilter = new CharacterEncodingFilter();
		encodingFilter.setEncoding("UTF-8");
		return new Filter[] { encodingFilter };
	}
}

3. 기본적인 스프링 설정 파일 작성하기

Spring MVC에서 사용할 Bean들을 설정하는 스프링 설정 파일을 작성합니다.

여기에서는 'org.edwith.webbe.calculator.service' 패키지 이하의 Bean들만 찾도록 설정되어 있습니다.

 

ApplicationConfig.java

package org.edwith.webbe.calculator.config;

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

@Configuration
@ComponentScan(basePackages = {"org.edwith.webbe.calculator.service"})
public class ApplicationConfig {
}

4. Spring MVC 설정 파일 작성하기

MvcConfig.java

package org.edwith.webbe.calculator.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.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

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


@Configuration
@EnableWebMvc
@EnableSwagger2
@ComponentScan(basePackages = {"org.edwith.webbe.calculator.controller.api"})
public class MvcConfig implements WebMvcConfigurer {
	// DefaultServlet에 대한 설정을 합니다.
	// DispatcherServlet이 처리하지 못하는 URL은 DefaultServlet이 처리하게 됩니다.
	// 해당 설정이 없으면 자동 생성된 Swagger 페이지를 볼 수 없습니다.
	@Override
	public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
		configurer.enable();
	}

/*
    	Swagger 사용 시에는 Docket Bean 을 품고있는 설정 클래스 1개가 기본으로 필요하다.
    	Spring Boot 에서는 이 기본적인 설정파일 1개로 Swagger 와 Swagger UI 를 함께 사용가능하지만,
    	Spring MVC 의 경우 Swagger UI 를 위한 별도의 설정이 필요하다.
    	이는, Swagger UI 를 ResourceHandler 에 수동으로 등록해야 하는 작업인데,
    	Spring Boot 에서는 이를 자동으로 설정해주지만 Spring MVC 에서는 그렇지 않기 때문이다.
     */
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2)
				.select()
				.apis(RequestHandlerSelectors.any()) // // 현재 RequestMapping으로 할당된 모든 URL 리스트를 추출
				.paths(PathSelectors.ant("/api/**"))// PathSelectors.any() 를 할경우 모든 경로가 다 사용된다. RestController가 아닌 것 까지 사용된다.
				.build()
				.apiInfo(apiInfo())
				.useDefaultResponseMessages(false);
	}

	/**
	 * API Info
	 */
	private ApiInfo apiInfo() {
		Contact contact = new Contact("강경미", "https://www.edwith.org", "carami@edwith.org");
		ApiInfo apiInfo =
				new ApiInfo("Swagger Sample", "APIs Sample", "Sample Doc 0.1v", "", contact, "This sentence will be display.", "/");
		return apiInfo;
	}
}

클래스 위에 @EnableWebMvc, @EnableSwagger2가 붙어 있는 것을 확인할 수 있습니다.

각각 Spring MVC설정, Swagger2설정이라는 것을 의미합니다.

해당 어노테이션이 붙어 있을 경우 Spring MVC와 Swagger2의 기본 설정이 자동으로 설정됩니다.

Swagger2를 사용하려면 Docket객체를 Bean으로 설정해야 합니다.

Docker객체에는 어떤 경로의 Web API들을 자동으로 문서화 할 것인지에 대한 설정과 문서 설명에 대한 내용이 포함됩니다.

여기까지 설정하였다면, Web API를 작성하고 스웨거를 이용할 준비가 완료되었습니다.

---

3) Swagger-ui 확인 및 기능 테스트하기

swagger-ui