[Spring] Swagger

안녕하세요. J4J입니다.

 

이번 포스팅은 Swagger에 대해 적어보는 시간을 가져보려고 합니다.

 

 

Swagger란?

 

스웨거는 개발자가 Rest API를 만들고 만든 Rest API에 대한 설계, 빌드, 문서화 등을 도와주는 오픈 소스 프레임워크입니다.

 

간단하게 말하자면 스프링으로 만든 Rest API를 한눈에 볼 수 있도록 자동화해준다고 생각합니다.

 

 

사용 이유

 

스웨거를 사용하는 이유는 협업을 위한 API 문서 자동화입니다.

 

개발 요건에 맞게 구현된 Rest API는 적게는 한 곳, 많게는 여러 곳에서 클라이언트 화면을 구성하기 위한 데이터를 호출하기 위해 사용됩니다.

 

결과적으로 API를 사용하기 위해 파라미터 값은 무엇이고 리턴 값은 무엇인지 등의 정보가 필요했고 스웨거는 관련 데이터를 스웨거만 보며 이해할 수 있도록 도와줍니다.

 

또한 빌드도 할 수 있기 때문에 실제 클라이언트 화면에서 Rest API를 가져다 사용하는 것처럼 정보를 입력하여 빌드를 해볼 수도 있습니다.

 

 

적용 방법

 

※ 스프링과 관련된 코드는 모두 STS-3.9.12.RELEASE 버전을 기준으로 작성되었습니다.

 

[ 1. pom.xml에 dependency 추가 ]

 

<!-- Swagger -->
<dependency>
	<groupId>io.springfox</groupId> <!-- Swagger 사용을 위한 dependency -->
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId> <!-- Swagger 사용을 위한 dependency -->
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

<!-- Data Binding -->
<dependency> <!-- JSON 데이터 처리를 위한 dependency -->
	<groupId>com.fasterxml.jackson.core</groupId>
	<artifactId>jackson-databind</artifactId>
	<version>2.9.8</version>
</dependency>

 

 

[ 2. 스웨거 설정을 위한 클래스 생성 (com.spring.swagger.config.SwaggerConfig) ]

 

package com.spring.swagger.config;

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

import springfox.documentation.builders.ApiInfoBuilder;
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;

@EnableSwagger2
@Configuration
public class SwaggerConfig {
	
	private ApiInfo metadata() {
		return new ApiInfoBuilder().title("project title") // 제목
								   .description("project description") // 설명
								   .version("1.0") // 버전
								   .build();
	}

	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2).select()
												      .apis(RequestHandlerSelectors.any()) // 모든 패키지에 대해 적용, any대신 basePackage를 이용하여 패키지 선택 가능
												      .paths(PathSelectors.any()) // 모든 URL에 대해 적용, any대신 ant를 이용하여 특정 URL만 선택 가능 
												      .build()
												      .apiInfo(metadata());
	}
}

 

 

반응형

 

 

[ 3. servlet-context.xml 설정 추가 ]

 

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/mvc"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:beans="http://www.springframework.org/schema/beans"
	xmlns:context="http://www.springframework.org/schema/context"
	xsi:schemaLocation="http://www.springframework.org/schema/mvc https://www.springframework.org/schema/mvc/spring-mvc.xsd
		http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/context https://www.springframework.org/schema/context/spring-context.xsd">

	...
    
	<resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
	<resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />

	...
	
	<context:component-scan base-package="com.spring.swagger.controller, com.spring.swagger.config" /> <!-- 컨트롤러와 설정파일들에 해당 설정을 적용 -->
</beans:beans>

 

 

[ 4. 프로젝트 실행 후 기본 URL에 /swagger-ui.html을 입력 ]

 

Swagger Execution

 

 

Controller에 정보 입력

 

※ 스프링과 관련된 코드는 모두 STS-3.9.12.RELEASE 버전을 기준으로 작성되었습니다.

 

위와 같이 스웨거 화면을 띄울 수 있기 때문에 이제 간단한 컨트롤러를 작성해보겠습니다. (com.spring.swagger.controller.MyController)

 

package com.spring.swagger.controller;

import java.util.ArrayList;
import java.util.List;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@RestController
@Api(value = "myController", description = "myController에 대한 설명을 작성") // Controller에 대한 설명을 작성
public class MyController {
	
	@ApiOperation(value = "이름 리턴", notes = "이름을 받아 리턴해주는 메서드입니다.") // 매핑되는 메서드에 대한 설명
	@GetMapping("/getName")
	public String getName(@RequestParam String name) {
		return "myName is " + name;
	}
	
	
	@ApiOperation(value = "리스트 리턴", notes = "문자열 리스트를 리턴해주는 메서드입니다.") // 매핑되는 메서드에 대한 설명
	@GetMapping("/getArray")
	public ResponseEntity<Object> getArray() {
		List<String> list = new ArrayList<String>();
		list.add("first");
		list.add("second");
		
		return new ResponseEntity<Object>(list, HttpStatus.OK);
	}
}

 

 

위와 같이 컨트롤러를 작성하고 스웨거를 다시 들어갈 경우 다음과 같이 MyController에 대한 정보가 나옵니다.

 

Execution Swagger after Making Controller

 

 

728x90

 

 

my-controller를 클릭하면 작성된 메서드들이 나오고 메서드들 중 getName을 클릭하면 다음과 같은 화면이 나옵니다.

 

getName in Swagger

 

 

여기서 Try it out을 누르면 파라미터로 넣을 수 있는 값을 입력할 수 있도록 나오고 값을 입력한 뒤 Execute를 누를 경우 Rest API가 리턴해주는 Response값을 확인할 수 있습니다.

 

GetMapping Response in Swagger

 

 

ServletContext 파일 변경 (xml → Java)

 

이전 포스팅들에서도 xml로 작성된 servlet-context파일을 Java로 변경한 적이 있었는데 이번에도 Java로 변경하여 Swagger를 사용해보도록 하겠습니다.

 

[ 1. servlet-context.xml 파일 수정 ]

 

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/mvc"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:beans="http://www.springframework.org/schema/beans"
	xmlns:context="http://www.springframework.org/schema/context"
	xsi:schemaLocation="http://www.springframework.org/schema/mvc https://www.springframework.org/schema/mvc/spring-mvc.xsd
		http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/context https://www.springframework.org/schema/context/spring-context.xsd">

   <!-- Java -->
   <context:annotation-config></context:annotation-config>
   <beans:bean class="com.spring.swagger.config.ServletContext"></beans:bean>
	
   <!-- xml -->
   ...
    
</beans:beans>

 

 

[ 2. ServletContext 클래스 파일 생성 (com.spring.swagger.config.ServletContext) ]

 

package com.spring.swagger.config;

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
@EnableWebMvc
@ComponentScan(basePackages = {"com.spring.swagger.controller", "com.spring.swagger.config"}) // 컨트롤러와 설정파일들에 해당 설정을 적용
public class ServletContext implements WebMvcConfigurer {
	
	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
    	
        	...
        
		registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); // swagger 등록
		registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); // swagger 등록
	}
}

 

 

[ 3. 정상적으로 화면이 표출되는 것을 확인 ]

 

Swagger UI

 

 

참고

 

[Spring]Spring MVC에 Swagger 적용하기

 

 

 

 

이상으로 Swagger에 대해 간단하게 알아보는 시간이었습니다.

 

읽어주셔서 감사합니다.