SpringBoot集成Knife4j報錯：文件上傳不顯示文件域問題的解決方案

更新時間：2025年05月30日 09:45:18 作者：LOVE_DDZ

在使用 Knife4j 為 Spring Boot 項目生成 API 文檔時,開發(fā)者可能會遇到文件上傳功能不顯示文件域的問題,本文將詳細(xì)介紹如何解決這一問題,并提供完整的解決方案,需要的朋友可以參考下

Spring Boot 中集成 Knife4j：解決文件上傳不顯示文件域的問題

在使用 Knife4j 為 Spring Boot 項目生成 API 文檔時，開發(fā)者可能會遇到文件上傳功能不顯示文件域的問題。本文將詳細(xì)介紹如何解決這一問題，并提供完整的解決方案。

Knife4j官網(wǎng)

一、環(huán)境版本

Spring Boot：2.7.4
Knife4j：3.0.3

二、問題描述

在使用 Knife4j 配置文件上傳接口時，文件上傳的表單域可能無法正常顯示，導(dǎo)致無法選擇文件進(jìn)行上傳。即使使用了 @ApiParam 注解的 type 或 format 屬性，問題仍然存在。

三、解決方案

1. 使用 @RequestPart 注解

在 Spring Boot 中，@RequestPart 注解用于處理 multipart/form-data 類型的請求參數(shù)，適用于文件上傳場景。通過正確使用 @RequestPart 注解，可以確保 Knife4j 能夠正確識別文件上傳的表單域。

示例代碼

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

@RestController
@RequestMapping("/file")
public class FileController {

    @ApiOperation(value = "文件上傳接口")
    @PostMapping("/upload")
    public String uploadFile(@RequestPart @RequestParam("file") MultipartFile file) {
        if (file.isEmpty()) {
            return "文件為空，請選擇文件";
        }
        // 處理文件上傳邏輯
        return "文件上傳成功";
    }
}

2. 配置 Knife4j

確保 Knife4j 的配置類正確配置了 API 文檔的路徑和包掃描。以下是一個典型的 Knife4j 配置類示例：

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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
@EnableKnife4j
public class Knife4jConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.package"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API 文檔")
                .description("API 文檔描述")
                .version("1.0")
                .build();
    }
}

3. 檢查 Spring Security 配置

如果項目中使用了 Spring Security，確保放行了 Knife4j 和 Swagger 相關(guān)的路徑。例如：

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .requestMatchers("/api/auth/**").permitAll()
            .requestMatchers("/doc.html", "/webjars/**", "/swagger-resources/**", "/v3/**").permitAll()
            .anyRequest().authenticated();
    }
}

4. 兼容性處理

對于 Spring Boot 2.6+，可能需要額外的兼容性處理。以下是一個兼容性處理的示例：

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;

import java.util.List;
import java.util.stream.Collectors;

@Configuration
public class Knife4jCompatibilityConfig {

    @Bean
    public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
        return new BeanPostProcessor() {
            @Override
            public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
                if (bean instanceof RequestMappingHandlerMapping) {
                    customizeSpringfoxHandlerMappings(((RequestMappingHandlerMapping) bean).getHandlerMethods().keySet());
                }
                return bean;
            }

            private void customizeSpringfoxHandlerMappings(List<String> mappings) {
                List<String> copy = mappings.stream()
                        .filter(mapping -> !mapping.contains("PatternParser"))
                        .collect(Collectors.toList());
                mappings.clear();
                mappings.addAll(copy);
            }
        };
    }
}