Spring boot) Swagger 를 통한 문서화

Swagger란? 

 - Open Api Specification(OAS)를 위한 프레임워크이다.

 - API 서비스를 설계하고 문서화 할 수 있게 해준다.

 

Swagger를 사용하는 이유

개발자들이 개발을 하면서 문서화에 신경을 쓴다는것은 당연히 해야하는것을 알지만 바쁜 일정이나 귀찮음 때문에 조금씩 미루게 되는 숙제같은 존재이다. Swagger는 Controller에 명시된 어노테이션을 스스로 해석해 API 문서를 자동으로 만들어줘 이러한 문서화 숙제에서 개발자들을 어느정도 자유롭게 풀어줄 수 있는 장점을 가진다.

 

아래 사이트를 통해 Swagger의 5가지 기능에 대해 알 수 있다.

https://swagger.io/about/

 

 

1. Design(설계)

표준 사양에 따라 API를 설계하고 모델링할 수 있다.

 

2. Build(구축)

Swagger는 JAVA에 종속되어있지 않다. 따라서 거의 모든 언어를 통해 안정적인 코드를 구축할 수 있다.

 

3. Document(문서화)

사실상 Swagger의 핵심기능이라고 생각되는 문서화는 개발자와 클라이언트 혹은 그 외 사용자에게 커뮤니케이션이 용이하게 만들어준다.

 

4. Test

API의 간단한 테스트를 진행할 수 있다.

 

5. Standardize(표준화)

API아키텍쳐 전반적으로 API 스타일을 가이드에 맞게 설정하고 시행한다.

 

 

Swagger 사용법

 

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

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

 

그리고 SwaggerConfig.java 클래스를 생성해준다.

		
import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;

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.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
@EnableSwagger2
public class SwaggerConfig {
	
	private static final Contact DEFAULT_CONTACT = new Contact("gh", "http://naver.com", "rlg1133@naver.com");

	private static final ApiInfo DEFAULT_API_INFO = new ApiInfo("awesome api title", "my user management rest api service", "1.0", "urn:tos",DEFAULT_CONTACT
			, "apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<>());
	
	private static final Set DEFAULT_PRODUCES_AND_CONSUMES = new HashSet<>(
			Arrays.asList("application/json", "application/xml")
			);
	
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(DEFAULT_API_INFO)
				.produces(DEFAULT_PRODUCES_AND_CONSUMES)
				.consumes(DEFAULT_PRODUCES_AND_CONSUMES)
				.select()
				.apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.any())
				.build();
	}
}

		

 

// @EnableSwagger2 Swagger2 버전을 활성화 해준다는 어노테이션

 

Docket : Swagger설정의 핵심 Bean으로 아래와 같은 설정값을 가진다.

 - apiInfo() : 제목과 설명 등 문서의 정보를 보여주기 위해 호출한다.

 - produces(), consumes() : 데이터를 주고받는 MIME타입(미디어 타입) 유형을 지정 

 - select() : ApiSelectorBuilder를 생성

 - apis() : api 스펙이 작성되어있는 패키지를 지정 -> 컨트롤러가 존재하는 페이지를 베이스로 RequestMapping이 선언된 API를 문서화 시킴

 - paths() : apis()에서 선택된 API 중 특정 path에 맞는 API를 다시 필터링해 문서화함