使用Rust Utoipa时，如何让Swagger UI显示带文件上传字段的multipart/form-data？

我明白你现在遇到的问题了——配置了Utoipa的文件上传接口后，Swagger UI里没出现预期的文件选择按钮，反而显示了普通的输入项，这确实挺让人头疼的。我来帮你梳理下解决思路和具体步骤：

核心问题：结构体字段的Schema标记缺失 #

你代码里用到的UploadedFile结构体是关键，Utoipa需要明确知道哪个字段是文件类型，才能在Swagger UI中渲染出文件选择按钮。如果结构体里的文件字段没有正确标记，Swagger就会把它当成普通字段处理。

解决方案1：给自定义结构体的文件字段添加正确标记 #

首先确保你的UploadedFile结构体实现了ToSchema，并且给文件字段加上#[schema(format = "binary")]标记，示例如下：

use utoipa::ToSchema;

#[derive(ToSchema)]
struct UploadedFile {
    // 如果你有普通表单字段，正常定义即可
    #[schema(example = 1001)]
    user_id: i32,
    // 核心：给文件字段加上binary格式标记
    #[schema(format = "binary", description = "要上传的文件")]
    file: Vec<u8>,
}

然后保持你的接口路径配置不变，或者可以额外加上encoding配置来明确告诉Swagger如何处理文件字段：

#[utoipa::path(
    post,
    path = "/upload",
    request_body(
        content_type = "multipart/form-data",
        content = UploadedFile,
        description = "上传的文件及关联信息",
        // 可选：明确指定文件字段的编码方式
        encoding = {
            "file": {
                style = "form",
                explode = true,
                content_type = "application/octet-stream"
            }
        }
    ),
    responses(
        (status = 200, description = "上传成功")
    )
)]
async fn upload() -> impl IntoResponse {
    todo!()
}

解决方案2：直接使用Utoipa的File类型（适用于简单上传场景） #

如果你不需要自定义结构体，只是单纯上传文件，可以直接用utoipa::File类型来定义请求体：

use axum::extract::Multipart;
use utoipa::File;

#[utoipa::path(
    post,
    path = "/upload",
    request_body(
        content_type = "multipart/form-data",
        content = Vec<(String, File)>,
        description = "单个或多个上传文件"
    ),
    responses(
        (status = 200, description = "上传成功")
    )
)]
async fn upload(multipart: Multipart) -> impl IntoResponse {
    // 这里编写处理Multipart的逻辑
    Ok("文件上传成功")
}

额外检查：确保依赖版本兼容 #

有时候旧版本的Utoipa或Swagger UI组件可能存在渲染问题，建议使用最新的稳定版依赖，比如在Cargo.toml中配置：

[dependencies]
axum = "0.7"
utoipa = { version = "4", features = ["swagger-ui"] }
utoipa-swagger-ui = "4"

做完这些修改后，重启服务并刷新Swagger UI页面，应该就能看到预期的文件选择按钮了。

备注：内容来源于stack exchange，提问作者Fuhua Zhang