[ Springboot ] Swagger 설정 및 접속 ( + Swagger Spring Security 설정 )

 

 

 

Springboot 환경에 Swagger를 설정하고 접속까지 해보겠습니다. 

 

 

프로젝트 환경 : Java 17 , SpringBoot 3.1.2 , ( spring security 적용되어 있음.)

 

 

 

 

 

Build.gradle

 

스웨거 의존성을 추가해 줍니다.

// Swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

 

 

SwaggerConfig 

 

 

swagger 를 사용하기 위해 설정 파일을 만들어 주겠습니다.

@OpenAPIDefinition(
        info = @Info(title = "sns",
                description = "sns api - personal project",
                version = "v1")
)
@RequiredArgsConstructor
@Configuration
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi snsOpenApi(){
        String[] paths = {"/v1/**"}; // /v1 로 시작하는 api 를 Swagger 로 볼 수 있음. 

        return GroupedOpenApi.builder()
                .group("sns")
                .pathsToMatch(paths)
                .build();
    }
}

 

 

Security 설정을 하지 않으신 분은 여기까지 설정 후 http://localhost:8080/swagger-ui/index.html 접속을 합니다.

그럼 아래와 같이 컨트롤러에서 정의한 api 를 확인할 수 있습니다. 

 

만약 아래와 같은 화면이 뜨지않고

응답이 403 또는 404이거나

failed to load remote configuration 또는

No operations defined in spec!이라면 문제 해결을 위해 조금 더 살펴보도록 하겠습니다.

swagger 설정 성공 시 보이는 화면

 

 

1. 403 또는 404 ,  failed to load remote configuration

해당 문제는 spring security에서 swagger 리소스를 허용하지 않아서 나는 문제입니다. 

 

 

 

우선 가장 기본 리소스인 /swagger-ui를 추가해 보겠습니다. 

좌 - 기존 설정 / 우 - 변경 후 

 

 

 

다시 http://localhost:8080/swagger-ui/index.html  접속해 보면 아래와 같이 failed to load remote configuration 문구가 보입니다. 

그리고 F12 또는 개발자 모드로 확인해 보면 ,  http://localhost:8080/v3/api-docs/swagger-config  가 요청되었지만 권한이 없음을 확인할 수 있습니다. 

 

 

 

/v3/api-docs/** 를 추가해 보겠습니다.

 

 

 

그리고 다시  http://localhost:8080/swagger-ui/index.html  접속해 보면 아래와 같은 화면을 확인할 수 있습니다. 

swagger 설정 성공 시 보이는 화면

 

 

Security  FilterChaninConfig 설정 전체 코드 ↓

@Component
@RequiredArgsConstructor
public class WebFilterChainConfig {
    private final JwtUtils jwtUtils;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {

        return http.csrf(AbstractHttpConfigurer::disable)
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/v1/users/login",
                                "/v1/users/sign",
                                "/swagger-ui/**"
                                "/swagger-resources/**",
                                "/v3/api-docs/**"
                        )
                        .permitAll()
                        .anyRequest()
                        .authenticated())
                .addFilterBefore(new JwtFilter(jwtUtils), UsernamePasswordAuthenticationFilter.class)
                .logout(logout -> logout
                        .deleteCookies("jwtToken")
                        .logoutRequestMatcher(new AntPathRequestMatcher("/v1/users/logout"))
                        .logoutSuccessUrl("/v1/users/login"))

                .build();
    }
}

 

 

 

 

 

 

2.  No operations defined in spec!

아래 게시글로 대신하겠습니다! 

https://suhyeonlog.tistory.com/35

 

 

 

 

 

 

 

++ swagger에 api에 대한 설명 추가하기

 

api 에 대한 설명을 추가할 수 있습니다. 

 

 

 

 

Controller

 

위와 같이 controller에 @Operation 어노테이션을 추가하고 ,  summary와 description을 이용해 api에 대한 설명을 덧붙여 주면 됩니다! 

 

 

 

 

 

 

감사합니다.