SpringBoot集成Knife4j报错：文件上传不显示文件域问题的解决方案_Java

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