[Spring] Spring Security + Swagger2 연결

Spring을 사용한 프로젝트를 할 때 API를 하나하나 적는 것은 많은 시간과 노력을 요구한다.

이에 자동화 된 API 툴을 제공하는데 그 중 Swagger를 연결하는 방법을 알아보겠다. (+마주했던 오류와 함께)

1. gradle 설정

// <https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui>
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
// <https://mvnrepository.com/artifact/io.springfox/springfox-swagger2>
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'

• gradle 설정을 먼저 진행한다.
• https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui 에서 맞는 버전을 선택한 후 gradle,maven 등 자신에게 맞는 환경을 선택한 후 나오는 것 고대로 복사해서 사용하면 된다.
• 여기서는 2.9.2 버전을 사용하겠다.
• 수정했다면 코끼리 새로고침 클릭

 

2. SwaggerConfig 파일 작성

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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 //swagger에 해당하는 어노테이션을 작성한다.
@EnableWebMvc //이것도 함께 작성
public class SwaggerConfig implements WebMvcConfigurer {

    //swagger 2.9.2 버전 리소스 등록
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) { //spring-security와 연결할 때 이 부분을 작성하지 않으면 404에러가 뜬다.
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    @Bean
    public Docket api() { //swagger를 연결하기 위한 Bean 작성
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() { //선택
        return new ApiInfoBuilder()
                .title("Omoolen Release") //자신에게 맞는 타이틀을 작성해준다.
                .description("backend api document") //알맞는 description을 작성해준다.
                .version("0.0") //알맞는 버전을 작성해준다.
                .build();
    }
}

• 자신의 홈 패키지 (com.example.examp 는 예시다- 자신이 설정한 패키지명) 아래에 config 패키지를 생성한 후, 바로 아래에 SwaggerConfig 파일을 생성한다.
• 자세한 내용은 주석으로 달아놓았다.
• SpringSecurity를 사용한다면 후에 http://localhost:8080/swagger-ui.html 에 접속하게 되면 404 오류가 뜬다.

  public class SwaggerConfig implements WebMvcConfigurer {
  //WebMvcConfigurer를 implement하고 아래 코드를 override한다.

  //swagger 2.9.2 버전 리소스 등록
      @Override
      public void addResourceHandlers(ResourceHandlerRegistry registry) { //spring-security와 연결할 때 이 부분을 작성하지 않으면 404에러가 뜬다.
          registry.addResourceHandler("swagger-ui.html")
                  .addResourceLocations("classpath:/META-INF/resources/");
          registry.addResourceHandler("/webjars/**")
                  .addResourceLocations("classpath:/META-INF/resources/webjars/");
      }

• → 리소스를 등록하는 코드를 작성한다.

 

 

3. SecurityConfig 파일에 swagger에 해당하는 부분을 제외하는 코드를 작성한다.

import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
import org.springframework.web.filter.CorsFilter;
~~import server.omoolen.config.security.jwt.JwtAuthenticationFilter;
import server.omoolen.config.security.jwt.JwtTokenProvider;~~
//jwt import 관련 cannot find symbol 오류 발생 시 Build > Rebuild Project 하고 다시 Run 시키기

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class
SecurityConfig extends WebSecurityConfigurerAdapter {

    private final CorsFilter corsFilter;
    ~~private final JwtTokenProvider jwtTokenProvider;~~

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.csrf().disable();

        http //swagger관련 보안 설정 위해 이 부분을 작성해주어야 한다.
                .authorizeRequests()
                .antMatchers("/api/v1/auth/**","/",
                        "/v2/api-docs", "/swagger-resources/**", "/swagger-ui/index.html", "/swagger-ui.html","/webjars/**", "/swagger/**",   // swagger
                        "/h2-console/**",
                        "/favicon.ico").permitAll()
                .anyRequest().authenticated();  // 나머지 API 는 전부 인증 필요

        http
                .headers()
                .frameOptions()
                .sameOrigin();

        ~~http
                .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                .and()
                .addFilter(corsFilter) // CORS 설정
                .formLogin().disable()
                .httpBasic().disable()
                .addFilterBefore(new JwtAuthenticationFilter(jwtTokenProvider), UsernamePasswordAuthenticationFilter.class);~~
    }
}

• 나의 경우는 jwt토큰을 사용해서 따로 생성해 놓은 jwt관련 파일을 import해서 사용했는데, 이유는 모르겠지만 SecurityConfig파일을 수정하려고 할 때마다 import server.omoolen.config.security.jwt.JwtAuthenticationFilter; import server.omoolen.config.security.jwt.JwtTokenProvider; ~~~~부분에서 cannnot find symbol 에러가 났다.⇒ 정말 이유는 모르겠지만 Rebuild하면 된다.
• ⇒ 이유를 찾지 못하고 거의 이틀 삽질하다가 Build > Rebuild하고 다시 Run시키니까 아뿔싸 바로 잘 찾아서 실행시키는게 아닌가
• 혹시 jwt사용안했다면 줄찍 해놓은 부분은 포함하지 않아도 된다. (코드 앞 뒤에 ~~ 존재하는 부분)

 

 

 

4. 그 후 http://localhost:8080/swagger-ui.html 접속 시 아름다운 화면을 볼 수 있다.

 

 

참고 사이트

1. [Spring Security] Spring Security + H2 DB + Swagger 연동시 페이지 접근 예외 처리 https://bkjeon1614.tistory.com/666
2. [swagger2] Whitelabel Error Page https://pipe0502.tistory.com/entry/swagger2-Whitelabel-Error-Page
3. [SpringBoot] Swagger 설정하기 https://velog.io/@gillog/SpringBoot-Swagger-설정하기