[Spring] Swagger 2.x.x 버전 적용하는 방법

 

 

 

Swagger를 이용하면 API문서를 자동화할 수 있습니다.

Swagger 관련 글들이 유독 스프링부트 환경에서 적용하는 방법이 많아서, 스프링5 환경에서의 스웨거 초기 설정 법을 정리해 둡니다.

 

*스웨거 버전은 2.9.2 사용하였습니다.

 

---

 

1. pom.xml 의존성 추가

 

<properties>
    <io.springfox.swagger-version>2.9.2</io.springfox.swagger-version>
</properties>

<!-- ================ Swagger ================= -->
<dependencies>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${io.springfox.swagger-version}</version>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${io.springfox.swagger-version}</version>
    </dependency>
</dependencies>

 

swagger2와 swagger-ui 두가지를 설정합니다. 같은 버전을 공유하기 때문에 버전은 프로퍼티로 관리하였습니다.

pom.xml 파일을 수정한 후엔 꼭 update project를 진행합니다.

 

 

 

2. Config 클래스 작성

 

package com.weet.app.board.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 SwaggerConfig {

    private static final String API_NAME = "Community API";
    private static final String API_VERSION = "0.0.1";
    private static final String API_DESCRIPTION = "Weet Community API 명세서";
    
    @Bean
    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.weet.app.board.controller"))
                .paths(PathSelectors.ant("/board/**"))
                .build();
    } // api

    public ApiInfo apiInfo() {
    	
        return new ApiInfoBuilder()
            .title(API_NAME)
            .version(API_VERSION)
            .description(API_DESCRIPTION)
            .build();
    } // apiInfo

} // end class

 

SwaggerConfig 클래스를 작성합니다. 

@EnableSwagger2 어노테이션은 필수로 작성해야 합니다.

 

apiInfo() 메소드에 api의 이름, 버전, 설명을 추가할 수 있습니다.

 

프로젝트의 특정 패키지만 api문서로 관리하고 싶을 땐 basePakage에 패키지명을 입력하면 됩니다.

PathSelectors.ant()에 URI Pattern을 넣어주면 지정한 URI에만 스웨거가 적용됩니다.

따로 URI를 지정하지 않는다면 Path.Selectors.any()를 사용합니다.

 

 

 

3. Servlet-context.xml에 빈 등록

 

<beans:bean id="swagger2Config" class="com.weet.app.board.config.SwaggerConfig"/>
<resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<resources location="classpath:/META-INF/resources/webjars/"  mapping="/webjars/**"/>

 

 

작성한 Config 클래스를 빈으로 등록합니다. 또한, api문서를 화면으로 출력하기 위한 swagger-ui.html의 경로와 자원파일들의 경로도 지정합니다. 이전에는 따로 설정이 필요 없었지만, 특정 버전 이상부터는 이렇게 직접 지정해주어야 경로를 찾을 수 있다고 합니다. 

 

이 설정이 매우 중요합니다!

02:52:23.370  WARN --- [http-nio-8080-exec-8] o.s.w.s.PageNotFound.noHandlerFound:1281 - No mapping for GET /swagger-ui.html

올바르게 설정한 것 같은데 계속

 

1. No mapping for GET /swagger-ui.html 오류가 뜨고,

2. /v2/api-docs는 제대로 출력될 때

 

해당 설정을 놓치지 않았는지 확인해봐야 합니다.

 

 

---

 

정상 설정 되었는지 확인하기

 

 

 

테스트 용으로 스웨거가 스캔할 대상의 컨트롤러에 메소드를 작성하였습니다.

서버를 구동시키고, http://localhost:8080/swagger-ui.html 로 접속합니다.

 

 

이렇게 작성한 api 리스트가 뜨면 성공입니다.

 

---

 

+) swagger-ui.html이 계속 안떠서 인터넷 검색을 많이 했는데, Config 클래스에서 WebMvcConfigurer 인터페이스를 implements하는 방식, WebMvcConfigurationSupport 클래스를 상속받는 방식이 정말 많이 나왔습니다. 그러나 해당 방법은 스프링에선 작동하지 않았습니다. 따라서 스프링 환경에서 개발시에는 위의 방법대로 서블릿 컨텍스트 설정을 해주셔야 잘 작동합니다.