Spring boot에 Swagger 적용하기(Maven)

Swagger란?

스웨거는 Web API 문서화를 위한 도구이다. 일반적으로 프로그램을 개발할 때, 백엔드 개발자와 프론트엔드 개발자가 서로 협력하는 형태로 개발을 진행하게 된다.
이 때, 클라이언트 - 서버 사이에서 어떠한 방식으로 데이터를 주고 받을지에 대한 명세가 필요할 수 있다. 이러한 내용이 담긴 문서를 일반적으로 API 명세서라고 말한다.

Swagger의 기능

• API 설계
• API 개발
• API 테스트
• API 모킹 및 시각화
• API 모니터링
• API 관리

Spring boot에 Swagger 적용

패키지 적용(Maven)

pom.xml에 아래와 같은 패키지를 적용해준다.

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>3.0.0</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>3.0.0</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-boot-starter</artifactId>
	<version>3.0.0</version>
</dependency>

설정

먼저 SwaggerConfig라는 클래스를 생성하고 아래와 같이 작성해준다.

package io.seho100.server.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

그리고 메인 클래스 파일에

@SpringBootApplication
@EnableSwagger2
public class ServerApplication {

}

위처럼 EnableSwagger2 어노테이션을 추가해준다. 그러고 나서, Swagger UI를 적용(localhost:8080/swagger-ui/index.html)로 접속해주면 생성한 컨트롤러 별로 input, output을 확인할 수 있으며 심지어 그 안에서 API 테스트도 할 수 있다는 것을 확인할 수 있다.

Spring Security와 Swagger

아직 Spring Security를 적용하지는 않았지만 추후에 적용 예정에 있기에 이 내용 또한 정리해본다.

만약 Spring boot 프로젝트가 Spring Security를 사용한다면 추가적으로 해야할 설정이 있다. 왜냐하면 기본적으로 Security에 예외 처리되지 않은 URL 매핑들은 필터를 거치지 않으면 통과시키지 않기 때문이다.

@Override
    protected void configure(HttpSecurity http) throws Exception {
        http.cors().and().csrf().disable()
                .authorizeRequests()
                .antMatchers("/user/signup", "/user/login", "/exception/**","/item/**", "/v2/api-docs", "/configuration/**", "/swagger*/**", "/webjars/**")
                .permitAll()
                .anyRequest()
                .authenticated()
                .and()
                .exceptionHandling().authenticationEntryPoint(new AuthenticationExceptionHandler())
                .and()
                .sessionManagement()
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS);

        http.addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class);
    }

antMatcher에 "/v2/api-docs", "/configuration/**", "/swagger*/**", "/webjars/**" 이 부분을 추가시켜주면 된다. 그러면 포스트맨에서 Swagger를 JSON 방식으로 확인할 수도 있고, Swagger UI로 생성된 API 문서를 html로 확인할 수도 있다.

직접 Swagger를 설정하고 테스트 해본 결과 Cors는 신경을 안써도 되는 것으로 확인이 되었는데, 공식 문서를 확인해보니 Swagger를 적용한 서버와 API 엔드포인트 서버가 동일하다면 따로 적용을 해주지 않아도 된다고 한다.

하지만 Swagger서버를 따로 운영해야 하는 경우에는 따로 Cors를 설정해주어야 한다. 설정 방법은 여기에서 볼 수 있다.