如何在Node.js的Swagger中实现文件上传动态参数名？

核心逻辑 #

通过代码动态修改Swagger的Schema定义，把固定的fileParam替换为用户配置的自定义参数名，同时保证后端接口的文件接收逻辑与之一致。

具体实现方案 #

1. 动态构建Swagger Schema（直接定义JS对象场景）

先写好固定参数的基础结构，再根据用户配置的参数名动态添加文件上传字段：

// 从配置文件/环境变量读取自定义文件参数名
const customFileParamName = process.env.UPLOAD_FILE_PARAM || 'file';

// 基础Swagger Schema结构
const swaggerBaseSchema = {
  properties: {
    environment: {
      type: 'string'
    }
  }
};

// 动态注入自定义文件上传参数
swaggerBaseSchema.properties[customFileParamName] = {
  type: 'string',
  format: 'binary'
};

// 将处理后的Schema传给swagger-ui-express等中间件

2. 修改swagger-jsdoc生成的Spec（注释生成文档场景）

如果用swagger-jsdoc从代码注释生成文档，可在生成Spec后动态修改字段名：

const swaggerJSDoc = require('swagger-jsdoc');
const customFileParamName = 'uploadFile'; // 从配置获取

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: { title: '文件上传API', version: '1.0.0' },
    paths: {
      '/api/upload': {
        post: {
          requestBody: {
            content: {
              'multipart/form-data': {
                schema: {
                  type: 'object',
                  properties: {
                    environment: { type: 'string' }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  apis: ['./routes/*.js']
};

// 生成初始Spec后修改字段
const swaggerSpec = swaggerJSDoc(swaggerOptions);
const uploadPathProps = swaggerSpec.paths['/api/upload'].post.requestBody.content['multipart/form-data'].schema.properties;
// 移除原固定字段
delete uploadPathProps.fileParam;
// 添加自定义字段
uploadPathProps[customFileParamName] = { type: 'string', format: 'binary' };

3. 中间件动态改写Swagger响应（静态JSON文件场景）

如果Swagger文档是静态JSON文件，可通过中间件在返回给前端时动态替换参数名：

const express = require('express');
const app = express();
const customFileParamName = app.get('config').uploadParamName; // 从应用配置获取

// 拦截Swagger JSON请求，动态修改字段
app.get('/swagger.json', (req, res) => {
  // 读取静态Swagger文件
  let swaggerDoc = require('./swagger.json');
  // 迁移原文件参数配置到自定义字段
  const fileProp = swaggerDoc.properties.fileParam;
  delete swaggerDoc.properties.fileParam;
  swaggerDoc.properties[customFileParamName] = fileProp;
  res.json(swaggerDoc);
});

配套后端逻辑 #

无论用哪种方案，后端接收文件的逻辑必须和Swagger定义的参数名一致，比如用multer时：

const multer = require('multer');
const upload = multer({ dest: './uploads/' });

// 参数名要和Swagger中配置的完全匹配
app.post('/api/upload', upload.single(customFileParamName), (req, res) => {
  // 处理上传的文件
  res.status(200).json({ filename: req.file.filename });
});

内容的提问来源于stack exchange，提问作者PraveenSelvam