Spring Boot 中集成 Knife4j：解决文件上传不显示文件域的问题

news2025/4/17 0:22:13

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 {

    @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 相关的路径。例如：

@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);
            }
        };
    }
}