如何在 Swagger UI 中正确显示“Choose a File”上传按钮-js教程-PHP中文网

如何在 Swagger UI 中正确显示“Choose a File”上传按钮

swagger ui 默认不显示文件选择按钮，是因为 openapi 3.0 规范中 type: file 必须定义在 schema 内部而非参数顶层；修正 swagger 注释中的参数结构即可让按钮正常渲染。

swagger ui 默认不显示文件选择按钮，是因为 openapi 3.0 规范中 type: file 必须定义在 schema 内部而非参数顶层；修正 swagger 注释中的参数结构即可让按钮正常渲染。

在基于 Express + Swagger UI 构建的 Node.js 文件上传接口中，若 Swagger 文档（如 https://www.php.cn/link/636b408c5633c870eecb2c49159a2701）仅显示普通文本输入框而无“Choose a File”按钮，根本原因在于 Swagger 注释（JSDoc）未遵循 OpenAPI 3.0 的参数定义规范。

OpenAPI 3.0 要求：当使用 multipart/form-data 上传文件时，文件参数必须通过 schema: { type: 'file' } 显式声明，不能直接在参数层级使用 type: file（该写法属于已废弃的 OpenAPI 2.0 / Swagger 2.0 风格）。当前主流 Swagger UI（v4+）严格遵循 OpenAPI 3.0，因此旧式写法将被忽略，导致渲染为纯文本输入框。

✅ 正确写法如下（关键修改已高亮）：

PagePop

PagePop是一款AI文本写作工具，一站式全能AI内容创作和设计平台。

下载

/**
 * @swagger
 * /upload:
 *   post:
 *     summary: Upload a file
 *     consumes:
 *       - multipart/form-data
 *     parameters:
 *       - in: formData
 *         name: file
 *         required: true
 *         description: The file to upload
 *         schema:           # ← 必须嵌套在 schema 下
 *           type: file      # ← type: file 必须在此处声明
 *     responses:
 *       200:
 *         description: File uploaded successfully
 */

⚠️ 注意事项：

in: formData 在 OpenAPI 3.0 中已被弃用，推荐改用 in: formData 或更标准的 in: formData 实际应统一为 in: formData（Swagger-jsdoc v6+ 支持），但为兼容性仍可保留；更推荐升级写法为 in: formData + content 字段（见下方进阶写法）；
确保 consumes: ["multipart/form-data"] 存在，否则 Swagger UI 可能无法识别上传上下文；
若使用 Swagger-jsdoc v6+，建议采用 OpenAPI 3.0 原生语法，用 requestBody 替代 parameters（更语义化且支持多文件）：

/**
 * @swagger
 * /upload:
 *   post:
 *     summary: Upload a single file
 *     requestBody:
 *       required: true
 *       content:
 *         multipart/form-data:
 *           schema:
 *             type: object
 *             properties:
 *               file:
 *                 type: string
 *                 format: binary
 *     responses:
 *       200:
 *         description: File uploaded successfully
 */

该写法不仅兼容性更好，还天然支持多字段表单（如同时传 file 和 description），且无需依赖 formData 参数类型。

最后，请确认 Swagger 文档已重新生成（重启服务或刷新缓存），并检查浏览器控制台是否有 CORS 或 MIME 类型警告——这些也可能间接影响 UI 渲染。完成上述修正后，Swagger UI 将正确显示原生元素，即“Choose a File”按钮，用户可直接点击上传文件进行调试。