Swagger 맛보기

Swagger는 구현된 REST기반의 API의 명세를 자동으로 만들어주는 도구입니다.

base package를 지정해주는 코드 몇라인만 작성하면, 해당 서비스에서 제공하는 모든 API 명세를 일목요연하게 보여주어 API설명을 위한 별도의 문서작업이 필요없게 됩니다. (자동화의 위력)  또한 간단한 API 테스트도 진행할 수 있습니다. 

Swagger 공식사이트에서는 Swagger를 아래와 같이 정의했습니다.

Swagger는 팀이나 개인이 API 설계, 문서화부터 테스트,배포까지 API의 모든 라이프사이클에 걸쳐 개발을 가능하게 해주는 파워풀하지만 쉽게 사용할수 있는 API 개발도구들의 모음입니다.

Swagger is a powerful yet easy-to-use suite of API developer tools for teams and individuals, enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

앞서 Spring Boot 시작하기에서 만든 코드에 SwaggerConfig.java를 추가해 간단히 Swagger를 적용해보고, 어떻게 사용하는지 알아봅니다.

1. build.gradle 파일의 dependency에 아래 코드추가

dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' testImplementation('org.springframework.boot:spring-boot-starter-test') { exclude group: 'org.junit.vintage', module: 'junit-vintage-engine' } //Swagger compile('io.springfox:springfox-swagger2:2.7.0'); compile('io.springfox:springfox-swagger-ui:2.7.0'); }

2,. Project Explorer 에서 Hello_MSA_World 프로젝트 선택후 마우스 우클릭 : Gradle > Refresh Gradle Project 선택

Progress 창을 보면 Swagger 관련 라이브러리를 다운로드 받는것을 확인할 수 있습니다.

3. SwaggerConfig.java 추가 (HelloController.java와 동일한 위치)

package com.redcrow.Hello_MSA_World;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.builders.ApiInfoBuilder;

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 {

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

                .title("HelloAPI")

                .description("Hello MSA World API")

                .build();

}

@Bean

public Docket api() {

return new Docket(DocumentationType.SWAGGER_2).groupName("example").apiInfo(this.apiInfo()).select()

.apis(RequestHandlerSelectors.basePackage("com.redcrow.Hello_MSA_World"))

.paths(PathSelectors.any())

.build();

}

}

3. HelloMsaWorldApplication 실행

4. 브라우저에서 http://localhost:8081/swagger-ui.html 접속

접속하면 컨트롤러와 어플리케이션 클래스가 보이고 List Operations 링크를 누르면 아래처럼 API 목록이 조회되빈다..

각각의 API명을 누르면 확장되는데 상세 설명도 나옵니다. /hello2의 경우는 parameter를 받을수 있도록 @RequestParam으로 구현해서 parameter도 같이 보여집니다.

5. API 테스트

각 API의 "Try it out" 버튼을 누르면 API가 실행되고 아래와 같은 수행결과가 조회됩니다. API의 동작을 확인하는 Curl의 command 도 친절하게 생성해줍니다.

맛보기 끝