Swagger UI

Spring으로 Rest API를 개발한 이후 클라이언트 개발자에게 매번 문서로 정리하여 공유할 때, API에 대한 수정이 발생할 때마다 문서도 수정하여 다시 공유해야 하는 점이 번거롭고, 사실 문서 정리부터 번거롭다.

이때 Swagger를 사용하게 되면 API 문서 자동화로 따로 문서로 정리할 필요도 없을 뿐만 아니라 UI에서 직접 API를 테스트해볼 수 있기 때문에 편리하다.

즉, 서버로 요청되는 API 리스트를 HTML 화면으로 문서화하여 테스트할 수 있는 라이브러리이다. 이 라이브러리는 서버가 가동되면서 @RestController를 읽어 API를 분석하여 HTML 문서를 작성한다.

Swagger 의존성 추가

Swagger를 사용하기 위해 pom.xml에 다음과 같이 의존성을 추가해줘야 한다.

<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>

Swagger 설정 추가

다음과 같이 설정 클래스를 추가해주면 Swagger UI를 사용할 준비가 되었다.

package studio.thinkground.aroundhub.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;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("studio.thinkground.aroundhub"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Around Hub Open API Test with Swagger")
                .description("설명 부분")
                .version("1.0.0")
                .build();
    }
}

ApiInfo apiInfo()에는 API의 이름 및 설명, 버전 정보를 명시해주면 된다.

기능

다음과 같은 화면에서 API를 확인할 수 있다.
또한 다음과 같이 요청의 방식에 대해 파악할 수 있으며,
API 테스트를 통하여 응답도 파악할 수 있다.

참고)
어라운드허브 스튜디오