Swagger OpenAPI：GET请求数组参数选空选项时移除参数的方法

API 探路者

2026-7-3

解决Swagger UI中空数组查询参数的问题

问题背景

你定义了如下quality GET查询参数：

get:
  parameters:
    - name: quality
      description: Filter by "origin.quality" by comma separated value (i.e. AA,AB,BC).
      explode: false
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
          enum: [EE, AA, AB, AC, AD, BA, BB, BC, BD, CA, CB, CC, CD, DA, DB, DC, DD]

在Swagger UI中选择默认的“--”选项时，请求会携带quality=空参数，导致后端返回错误，需要实现选择该选项时自动移除这个参数。

可行解决方案

1. 启用Swagger UI的`skipEmptyParameters`配置

这是最简便的解决方案，只要你的Swagger UI版本为3.25.0及以上，即可支持该配置。在Swagger UI初始化时添加该配置，就能自动跳过空值参数：

const ui = SwaggerUIBundle({
  url: "你的OpenAPI规范文件路径",
  dom_id: '#swagger-ui',
  skipEmptyParameters: true, // 关键配置：移除空参数
  // 其他配置项...
});

2. 自定义请求拦截插件（兼容旧版Swagger UI）

如果无法升级Swagger UI版本，可以编写一个自定义插件，在请求发送前过滤掉空的查询参数：

// 定义移除空参数的插件
const removeEmptyQueryParams = () => ({
  requestInterceptor: (req) => {
    // 移除URL中值为空的查询参数
    req.url = req.url.replace(/([?&])[^=&]+=(?=&|$)/g, '')
                     .replace(/[?&]$/, '')
                     .replace(/^\?/, '');
    return req;
  }
});

// 初始化Swagger UI时注册插件
const ui = SwaggerUIBundle({
  url: "你的OpenAPI规范文件路径",
  dom_id: '#swagger-ui',
  plugins: [removeEmptyQueryParams],
  // 其他配置项...
});