Spring Boot에 Swagger2 (스웨거) 적용하기 (Maven)

환경

운영체제: Mac OS

Spring Boot 버전: 2.2.4.RELEASE

Maven 버전: 4.0.0

 

Swagger 란?

스웨거(Swagger)는 REST API 문서를 자동으로 생성해주는 오픈소스 프레임워크다.

 

자동으로 프로젝트의 코드를 읽고 API 문서를 생성해주기 때문에, API 스펙(Spec)이 바뀌어 API 문서들을 다시 수정하는 번거로움이 없다.

(매번 문서 작성하고... 수정하고... 리소스가 많이 들어가는 일이다. 이건 정말 좋은듯)

 

또한 스웨거가 제공해주는 UI 에서 실제로 REST API 를 던저보고 응답을 받을 수 있기 때문에 테스트도 할 수 있다.

 

Swagger2 적용하기

Swagger에도 버전이 존재하는데, 본 글에서는 Swagger2를 이용한다.

 

프로젝트 생성하기

2020/02/18 - [Spring Boot] - Spring Boot 프로젝트 생성하기

 

Gradle 을 이용하여 Swagger 2 적용하기

2020/03/07 - [Spring Boot] - Gradle 환경에서 Spring Boot 에 Swagger 2 적용하기

의존성 설정

pom.xml

<dependencies>
...

	<!-- Swagger 2 -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.9.2</version>
	</dependency>

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

...

</dependencies>

본 글에서는 스웨거 2.9.2 버전을 이용.

스웨거 설정 정보

TestContorller.java

• 예로 간단한 API 하나 생성했다.

package com.example.swagger.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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

@RestController
@RequestMapping("/api/v1")
public class TestController {

    @GetMapping("user/search")
    public Map<String, String> search() {
        Map<String, String> response = new HashMap<String, String>();
        response.put("name", "taehong.kim");
        response.put("age", "28");
        response.put("email", "xxxxxxxx@gmail.com");
        return response;
    }
}

 

SwaggerConfig.java

package com.example.swagger.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.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;

import java.util.Collections;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfo(
                "TEST API",
                "Some custom description of API.",
                "0.0.1",
                "Terms of service",
                new Contact("MemoStack", "https://memostack.tistory.com", "public.devhong@gmail.com"),
                "License of API", "API license URL", Collections.emptyList());
    }
}

 

브라우저를 통해 http://localhost:8080/swagger-ui.html 접속하면, 아래와 같이 API 문서를 생성해준다.

swagger-ui.html

Swagger를 통해 테스트를 해볼 수 있다.

Reference

• 위키백과 - https://ko.wikipedia.org/wiki/스웨거_(소프트웨어)