swagger 오류

지혜·2025년 2월 20일

💡 https://github.com/H5-dev-project/newsfeed

1. swagger 적용 이유

이번 팀 프로젝트에서는 로그인 시 발급받은 토큰을 HTTP header에 포함시켜 로그인 여부를 판단했다.
처음 swagger를 적용하기 이전에는 postman을 이용하여 테스트를 진행했으나, 이 경우에는 발급 받은 토큰을 테스트할 API의 header에 매번 값을 변경해주어야 한다는 불편함이 존재했다.
따라서 보다 편리한 테스트를 위해 swagger를 도입하기로 결정했다.

2. swagger 오류

📝 500 에러

swagger를 사용하기 위해 라이브러리를 추가하고 진행했으나 위의 내용 처럼 500 에러가 발생했다.
원인을 찾아보니 우리가 프로젝트에서 적용한 spring security에서 filterChain에 걸렸기 때문이었다.
그래서 filter에서 swagger 경로를 requestMatchers로 지정 후 permitAll()을 통해 예외 처리를 통해 filter에서 막히지 않도록 처리를 해주었다.

📌 코드 수정

@Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
                .csrf(AbstractHttpConfigurer::disable)
                .sessionManagement(session -> session
                        .sessionCreationPolicy(SessionCreationPolicy.STATELESS) // SessionManagementFilter, SecurityContextPersistenceFilter
                )
                .addFilterBefore(jwtSecurityFilter, SecurityContextHolderAwareRequestFilter.class)
                .formLogin(AbstractHttpConfigurer::disable) // UsernamePasswordAuthenticationFilter, DefaultLoginPageGeneratingFilter 비활성화
                .anonymous(AbstractHttpConfigurer::disable) // AnonymousAuthenticationFilter 비활성화
                .httpBasic(AbstractHttpConfigurer::disable) // BasicAuthenticationFilter 비활성화
                .logout(AbstractHttpConfigurer::disable) // LogoutFilter 비활성화
                .exceptionHandling(exception -> exception
                        .authenticationEntryPoint(jwtAuthEntryPoint)  // EntryPoint 등록
                )
                .authorizeHttpRequests(auth -> auth
                // ✅ 코드 추가
                        .requestMatchers("/swagger",
                                "/swagger-ui.html",
                                "/swagger-ui/**",
                                "/api-docs",
                                "/api-docs/**",
                                "/v3/api-docs/**")
                        .permitAll()                
                        .requestMatchers(
                                "/api/users/register",
                                "/api/users/login",
                                "/api/auth/refresh"
                        )
                        .permitAll()
                        .anyRequest().authenticated()
                )
                .build();
    }

📝 첨부파일 업로드 오류

첨부파일과 게시글 데이터를 같이 저장해야하는 부분이 존재했는데, swagger에서 json값을 인식하지 못해서 오류가 났다.
확인해본 결과 swagger UI는 @RequestPart 필드의 JSON값을 제대로 처리하지 못하는 문제가 존재한다는 것을 알았다.
그래서 기존 requestDto 값을 그대로 받았던 것을 String 형태로 먼저 받은 후 수동으로 requestDto로 변환하는 방식으로 해결했다.

📌 기존 코드)

@PostMapping("/api/boards")
    public ResponseEntity<ResponseDto<BoardResponseDto>> save(
            @UserSession AuthUsers authUsers, @RequestPart("board") BoardSaveRequestDto dto,
            @RequestPart(value = "file") MultipartFile file
            ) {
        return ResponseEntity.ok(boardService.save(authUsers, dto, file));
    }

📌 수정 코드)

// MULTIPART_FORM_DATA 형식으로 받기
@PostMapping(value = "/api/boards", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<ResponseDto<BoardResponseDto>> save(
            @Parameter(hidden = true) @UserSession AuthUsers authUsers,
            @RequestPart("board") @io.swagger.v3.oas.annotations.media.Schema(type = "string" , example = "{\"title\" : \"제목\" , \"content\" : \"내용\" , \"visibilityType\" : 1}")
            String boardJson, // String으로 받기
            @RequestPart(value = "file", required = false) MultipartFile file
    ) {
        try {
            // JSON을 BoardSaveRequestDto로 변환
            BoardSaveRequestDto dto = objectMapper.readValue(boardJson, BoardSaveRequestDto.class);
            return ResponseEntity.ok(boardService.save(authUsers, dto, file));
        } catch (Exception e) {
            return ResponseEntity.badRequest().build();
        }
    }