Swagger [1] 기본 개념 및 사용 방법

Swagger

Swagger란 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. 필자가 직접 사용해본 결과, 사용방법이 무척이나 간단하며 편리하게 API 문서화를 진행할 수 있다. 단점이라고 한다면, 이미 어느정도 개발이 완료된 프로젝트에 대해서는 적용이 다소 어려울 수 있다는 점이다. 이미 생성해놓은 모든 API에 별도 적용을 거쳐야 하기 때문이다... 신규 프로젝트에 도입할 때에는, 개발자들이 API Annotation 양식을 지켜가며 작성을 하게 함으로써 아주 간단하게 API 문서화를 할 수 있겠지만 말이다. 하단 출처에 적혀있는 Swagger 홈페이지에서 Demo 및 사용방법 등과 같은 정보를 확인할 수 있다.

 

---

 

Spring Boot 환경에서 적용하기

필자는 Spring Boot 환경에서 개발을 진행한다. Spring Boot 환경에서 Swagger를 사용하는 방법에 대해 알아보도록 하겠다.

 

---

 

Swagger Maven 추가하기

<!-- Swagger -->
<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 Config 생성

Swagger를 사용하기 위한 Config 설정이 필요하다. Configuration Annotation 설정 후, Swagger Config라는 Annotation을 별도 적용시켜주고, 하단에 구문을 기술하면 된다.

/**
 * Swagger 설정
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    private static final String API_NAME = "Swagger API 명세서 목록";
    private static final String API_VERSION = "0.0.1";
    private static final String API_DESCRIPTION = "Swagger API 명세서 Test 중...";
    
    /**
     * API
     */
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                ;
    }
    
    /**
     * API INFO
     */
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(API_NAME)
                .version(API_VERSION)
                .description(API_DESCRIPTION)
                .build();
    }
    
    private Set<String> getConsumeContentTypes() {
        Set<String> consumes = new HashSet<>();
        consumes.add("application/json;charset=UTF-8");
        consumes.add("application/x-www-form-urlencoded");
        return consumes;
    }
    
    private Set<String> getProduceContentTypes() {
        Set<String> produces = new HashSet<>();
        produces.add("application/json;charset=UTF-8");
        return produces;
    }
    
}

 

---

 

Swagger ui

상단에서 Swagger에 대해 간단하게 설명을 하였다. Demo를 확인할 수 있다고 했는데, 위의 설정을 마치면 우리도 간단하게 Swagger가 만들어준 API 명세서를 확인할 수 있다. Swagger를 실행한 URL(ex. localhost:8080)에 swagger-ui.html 을 입력해주면, swagger js가 알아서 API 명세서를 그리기 위한 API Annotaion data를 JSON으로 가공하고, 해당 JSON을 html에 뿌려준다. js가 난독화 되어있어 세부적인 사항을 파악하는 것에 어려움이 있지만, 대충 소스 및 작동 방식을 보았을 때 그렇다고 유추할 수 있었다. Swagger ui를 확인해보도록 하자.

여러분의 작업물은 필자의 작업물과 꽤나 다른 화면일 것이다. 필자가 기존에 설정해놓은 url pattern으로 인하여, /swagger-ui.html이 제대로 구동되지 않았을 뿐만 아니라, 필자는 Swagger ui를 수정하고 싶은 까닭으로 swagger js를 뜯어 내부 요소를 일부 수정하였기 때문이다. 다음 포스팅에서는 Swagger ui Custom에 대하여 알아보도록 하겠다.

 

 

 

---

 

 

 

[ 출처 ]

Swagger : https://swagger.io

Swagger 개념 : https://ko.wikipedia.org/wiki/스웨거_(소프트웨어)