Spring Boot 中集成 Knife4j：解决文件上传不显示文件域的问题
在使用 Knife4j 为 Spring Boot 项目生成 API 文档时，开发者可能会遇到文件上传功能不显示文件域的问题。本文将详细介绍如何解决这一问题，并提供完整的解决方案。
Knife4j官网
一、环境版本
- Spring Boot：2.7.4
- Knife4j：3.0.3
二、问题描述
在使用 Knife4j 配置文件上传接口时，文件上传的表单域可能无法正常显示，导致无法选择文件进行上传。即使使用了 @ApiParam 注解的 type 或 format 属性，问题仍然存在。
三、解决方案
1. 使用 @RequestPart 注解
在 Spring Boot 中，@RequestPart 注解用于处理 multipart/form-data 类型的请求参数，适用于文件上传场景。通过正确使用 @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 {@Beanpublic 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 相关的路径。例如：
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {@Overrideprotected 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 {@Beanpublic static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {return new BeanPostProcessor() {@Overridepublic 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);}};}
}
四、验证结果
按照上述步骤配置后，文件上传接口的文件域将能够正常显示。在 Knife4j 生成的文档中，文件上传的表单域将正确显示，用户可以正常选择文件进行上传。
