Spring Boot와 Spring Security 프로젝트에 Swagger 적용하기

이글의 목적은 프로젝트 API 개발을 어느정도 마치고 Swagger를 적용하는 방법을 정리하는 것이다.

적용하기에 앞서 이 프로젝트는 Spring Boot 2.6.2와 Spring Security가 적용되었다.

 

1. build.gradle에 의존성 추가

//for Swagger
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

 

2. SwaggerConfig 클래스 생성

config 패키지 내에 SwaggerConfig 클래스를 생성해준 뒤 다음과 같이 코드를 입력한다.

 

- api() 메소드의 apis()에는 해당 프로젝트의 패키지 경로를 입력해주어야 한다.

- apiInfoMetaData() 메소드에서는 Swagger ui에서 보여질 타이틀, 설명 정보를 설정할 수 있다.

package com.teamk.laube.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.teamk.laube.controller"))
                .paths(PathSelectors.ant("/*/**"))
                .build().apiInfo(apiInfoMetaData());
    }

    private ApiInfo apiInfoMetaData() {

        return new ApiInfoBuilder().title("NAME OF SERVICE")
                .description("API Endpoint Decoration")
                .contact(new Contact("Dev-Team", "https://www.dev-team.com/", "dev-team@gmail.com"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("1.0.0")
                .build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}

 

😵‍💫 발생했던 에러
먼저 처음에 코드 작성했을 때 발생한 에러는 EnableSwagger2 어노테이션에서 발생한 에러였다.
계속해서 NullPointerException이 발생하였고, EnableSwagger2 대신 EnableWebMVC 어노테이션을 사용해봤지만 해결되지 않았고, WebMvcConfigurationSupport 클래스를 상속받은 후 addResourceHandlers 메소드를 오버라이드했더니 Exception이 해결하였다!

 

3. Spring Security를 사용중이라면 경로 권한 부여하기

SecurityConfig 클래스에 들어가 권한 허용을 해준다.

.antMatchers(
    "/swagger-resources/**",
    "/swagger-ui.html",
    "/v2/api-docs",
    "/webjars/**",)
.permitAll()

 

구글링을 하다보니 swagger-ui.html으로 접속해야 할 지 swagger-ui/index.html으로 접속해야 할 지 버전에 따라 다르기 때문에 swagger-ui 404 에러가 종종 발생한다.

 

안정적으로 2.9.2버전을 사용한다면 localhost:8080/swagger-ui.html 로 접근하면 에러없이 swagger 페이지를 띄울 수 있다.

 

 

 

출처

https://velog.io/@gillog/Error-Swagger-2.9.2-swagger-ui.html-%EC%97%B4%EB%A6%AC%EC%A7%80-%EC%95%8A%EC%9D%84%EB%95%8C-%ED%95%B4%EA%B2%B0