swagger UI 설정

안녕하세요.

오늘은 Swagger UI를 사용해서 API문서를 자동화하는 방법에 대해서 포스팅하려고 합니다.

 

1. Why Swagger?

 

최근 Restful API를 많이 사용하면서, 클라이언트와 협업을 하기 위해서는 API문서가 중요합니다. API를 개발한 뒤, 수정사항이 빈번하게 발생해 API를 수정하게 되면, 문서를 일일히 수정하는 것은 많은 시간을 소요하게 됩니다.

따라서, API 문서를 자동화 하는게 좋은데, API 문서를 자동화 해주는 것들 중 IODocs와 Swagger 등이 많이 사용된다고 합니다. 오늘은 그 중 Swagger UI를 설정하고 간단하게 사용하는 방법에 대해서 포스팅하도록 하겠습니다.

 

 

2. 설정 방법

 

우선, 아래와 같이 pom.xml 파일에 dependency를 추가해줍니다.

<!-- swagger2 -->
<dependency>
	<groupid>io.springfox</groupid>
	<artifactid>springfox-swagger2</artifactid>
	<version>2.7.0</version>
</dependency>

 

저는, 스프링 부트를 사용해서 테스트를 진행하게 되어서 JAVA config설정을 찾아서 빈을 아래와 같이 설정해줍니다. 여기서, xml 설정을 원하시는 분들은 "spring swagger xml"을 검색하거나 swagger 문서를 찾아 보시면, 설정 법을 자세하게 확인하실 수 있습니다.

 

package com.example.demo.config;

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

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2)
				.select()
				.apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.any())
				.build();
	}
}

 

 다음으로는, Swagger를 문서로 확인하고 사용자와의 상호작용을 위해, Swagger UI를 추가하는 방법에 대해서 알아보겠습니다. 즉, Swagger UI는 Swagger에서 생성한 API문서와의 사용자 상호작용을 훨씬 쉽게 만들어주는 내장 솔루션입니다.

 

pom.xml파일에 아래와 같이 dependency를 추가해줍니다.

<!-- swagger UI -->
<dependency>
	<groupid>io.springfox</groupid>
	<artifactid>springfox-swagger-ui</artifactid>
	<version>2.7.0</version>
</dependency>

 

설정이 끝났으면, 브라우저의 주소 창에 http://localhost:8080/swagger-ui.html 를 입력해서 확인을 해보면 아래와 같은 화면을 볼 수 있습니다. 

 

 

 

테스트를 위해서 아래와 같이, 간단한 RestController를 만들어서 테스트 해보겠습니다.

 

package com.example.demo.controller;

import java.util.HashMap;
import java.util.Map;

import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.example.demo.domain.UserInfo;

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@RestController					// Rest Api임을 나타내주기위한 RestController 어노테이션 명시
@RequestMapping(value = "/api")
public class ApiTestController {

	@ApiOperation(value = "Api 테스트", response = UserInfo.class)
	@ApiImplicitParams({
		@ApiImplicitParam(name = "id", value = "아이디", required = true, dataType = "string", paramType = "query", defaultValue = ""), // 입력 받을 파라미터 명시
		@ApiImplicitParam(name = "password", value = "패스워드", required = true, dataType = "string", paramType = "query", defaultValue = "")  // 입력 받을 파라미터 명시
	})
	@RequestMapping(value = "/test", method=RequestMethod.POST)
	public Map<string, object=""> testApi(@RequestParam(value = "id", required = true) String id, 
						  			   @RequestParam(value = "password", required = true) String password) {
		
		Map<string, string=""> userMap = new HashMap<string, string="">();
		userMap.put("id", id);
		userMap.put("password", password);
		
		Map<string, object=""> resultMap = new HashMap<string, object="">();
		resultMap.put("userInfo", userMap);
		resultMap.put("responseCode", "success");
		
		System.out.println(resultMap);
		
		return resultMap;
	}
	
}
</string,></string,></string,></string,></string,>

 

코드를 작성 후 다시 localhost:8080/swagger-ui.html에 접속해 보시면 아래와 같은 화면을 확인할 수 있습니다.

 

 

화면을 확인하면서 아래의 Try it out! 버튼을 클릭하게 되면 로직이 돌면서 결과 값을 아래의 그림과 같이 리턴해줍니다.

 

 

이처럼, POST뿐만 아니라 GET, PUT, PATCH, DELETE 등도 구현을 하셔서 원하는 REST API를 설정하고 문서로 관리할 수 있습니다.

API를 이용하는 개발자들은 API를 개발하고 그것을 문서화 하는데 많은 이점을 가져온다고 생각합니다.

 

이것으로 Swagger UI 설정하는 방법에 대한 포스팅을 마치도록 하겠습니다.

 

참고 문서 : https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api