[프로젝트] 35. Swagger 추가

프로젝트에 Swagger를 추가하는 것은 API 문서화를 자동화하고, API의 사용 및 테스트를 편리하게 만드는 중요한 단계입니다. Swagger를 통해 개발자는 API의 엔드포인트, 파라미터, 응답 등의 세부 사항을 쉽게 이해할 수 있으며, API를 직접 시험해볼 수 있는 인터페이스를 제공받게 됩니다. 이 과정은 API 개발 및 테스트 과정을 간소화하고, API 사용자와의 커뮤니케이션을 개선하는 데 도움을 줍니다.

 

Gradle 설정

build.gradle 파일에 springdoc-openapi-ui 의존성을 추가하여 프로젝트에 Swagger를 통한 API 문서화 기능을 활성화합니다.

// swagger
implementation 'org.springdoc:springdoc-openapi-ui:1.6.15'

 

SecurityConfig 리팩토링

SecurityConfig에서는 Swagger가 제공하는 API 문서 및 UI에 접근할 수 있도록 관련 경로를 무시하도록 설정합니다. 또한, /api/auth/join, /api/auth/login 엔드포인트와 Swagger 관련 엔드포인트에 대해 인증 없이 접근을 허용합니다.

    // WebSecurity 설정
    public void configure(WebSecurity web) {
        web.ignoring().antMatchers("/static/css/**", "/static/js/**", "*.ico", // 정적 리소스 무시
                "/v2/api-docs", "/configuration/ui", "/swagger-resources", "/configuration/security",
                "/swagger-ui.html", "/webjars/**", "/swagger/**"); // Swagger 경로 무시
    }
    
    // HttpSecurity 설정
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .csrf().disable() // CSRF 보호 비활성화
            .authorizeRequests()
            .antMatchers("/api/auth/join", "/api/auth/login", "/swagger-ui/**", "/swagger-resources/**", "/v3/api-docs/**")
            .permitAll() // 인증 필요 없는 URL 설정
            .anyRequest().authenticated() // 그 외 요청은 인증 필요
            .and()
            .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) // 세션 정책: STATELESS
            .and()
            .formLogin().disable() // 폼 로그인 비활성화
    		.addFilterBefore(new JwtAuthenticationFilter(jwtTokenProvider, redisTemplate),
            	UsernamePasswordAuthenticationFilter.class); // JWT 인증 필터 추가
    }

 

SwaggerConfig 설정

SwaggerConfig 클래스를 정의하여, Swagger를 통한 API 문서화 설정을 커스터마이징합니다. JWT 인증이 적용된 API에 대해서도 Swagger UI를 통해 테스트할 수 있도록 Authorization 헤더를 추가하는 보안 스킴을 설정합니다.

@Configuration
@OpenAPIDefinition(servers = {@io.swagger.v3.oas.annotations.servers.Server(url = "/", description = "API Server")})
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi customTestOpenAPi() {
        return GroupedOpenApi
                .builder()
                .group("APIS")
                .addOpenApiCustomiser(buildSecurityOpenApi())
                .build();
    }

    public OpenApiCustomiser buildSecurityOpenApi() {
        return openApi -> openApi.addSecurityItem(new SecurityRequirement().addList("JWTAuth"))
                .getComponents()
                .addSecuritySchemes("JWTAuth", new SecurityScheme()
                        .name("Authorization") // 'Authorization' 헤더 이름
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")); // JWT 토큰 형식 지정
    }
}

 

JwtTokenProvider 수정

JwtTokenProvider에서는 Authorization 헤더에서 "Bearer " 접두사를 포함한 JWT 토큰을 추출할 수 있도록 resolveToken 메소드를 수정합니다. 이를 통해 Swagger UI에서 API를 테스트할 때 "Bearer [토큰]" 형식의 인증 헤더를 사용할 수 있습니다.

    // Request의 Header에서 token 값 가져오기 ("Bearer" 접두사 처리)
    public String resolveToken(HttpServletRequest request) {
        String bearerToken = request.getHeader("Authorization");
        if (bearerToken != null && bearerToken.startsWith("Bearer ")) {
            return bearerToken.substring(7); // "Bearer " 이후의 문자열을 반환
        }
        return null;
    }

 

결론

이러한 설정을 통해 Swagger를 활용한 API 문서화 및 인터페이스를 프로젝트에 성공적으로 추가할 수 있으며, API 개발 및 테스트 과정에서의 효율성과 사용자 경험을 크게 향상시킬 수 있습니다.