Node.js API使用Swagger测试时查询参数编码异常求助

核心原因：Swagger对type: any类型的查询参数会默认按**复杂结构（如JSON对象）**处理，自动执行x-www-form-urlencoded编码，导致URL出现大量转义字符（比如{变成%7B），后端无法正确解析过滤条件。而Insomnia会按你输入的原始内容传递参数，所以没有问题。

以下是具体解决步骤：

1. 替换any类型为明确的参数类型 #

不要用模糊的any，根据实际需求定义参数类型（如string/integer/boolean），或者拆分多条件为独立查询参数。

错误示例：

parameters:
  - name: filter
    in: query
    type: any
    required: true

修正示例（拆分多条件）：

parameters:
  - name: status
    in: query
    type: string
    required: true
  - name: minPrice
    in: query
    type: integer
    required: false

2. 若需传递复杂结构参数 #

如果必须用单个参数传递多条件过滤，将参数类型设为string，让用户传入JSON格式字符串，后端再解析为对象：

Swagger定义：

parameters:
  - name: filter
    in: query
    type: string
    example: '{"status":"active","minPrice":100}'
    required: true

Node.js后端解析：

// 注意处理JSON解析异常
let filter = {};
try {
  filter = JSON.parse(req.query.filter);
} catch (err) {
  return res.status(400).send('Invalid filter format');
}
// 用filter执行数据过滤逻辑

3. 检查Swagger UI配置 #

确认Swagger UI没有开启特殊的参数编码配置，比如部分自定义UI可能修改了queryConfig，保持默认的参数处理逻辑即可。

修改后测试：在Swagger UI中发送请求，查看URL栏的参数是否为原始格式（无过度转义），后端能正确接收并返回过滤后的结果。

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