Swagger-UI中JSON查询参数双重字符串化问题解析

问题背景

在Swagger-UI 5.x版本中，当使用OpenAPI 3.1.0规范定义包含对象数组的JSON查询参数时，会出现一个参数被双重字符串化的问题。这个问题会导致生成的URL不符合预期，影响API的正常调用。

问题现象

当定义一个接受对象数组的查询参数时，例如：

{
  "name": "param",
  "in": "query",
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "a": {"type": "string"},
            "b": {"type": "number"}
          }
        }
      }
    }
  }
}

预期生成的URL应该是将JSON数组直接编码：

?param=%5B%7B%22a%22%3A%22string%22%2C%22b%22%3A0%7D%5D

但实际生成的URL却对JSON进行了双重编码：

?param=%5B%22%7B%5C%22a%5C%22%3A%5C%22string%5C%22%2C%5C%22b%5C%22%3A0%7D%22%5D

技术分析

这个问题源于swagger-js库在处理JSON内容类型的查询参数时的序列化逻辑。当参数类型为数组且包含对象时，序列化过程会执行两次：

1. 第一次序列化：将数组中的每个对象转换为JSON字符串
2. 第二次序列化：将整个数组（现在包含JSON字符串而非对象）再次转换为JSON字符串

这种双重序列化导致最终生成的URL参数值不是原始数据结构的一次性JSON表示，而是包含了转义字符的嵌套JSON结构。

影响范围

该问题影响所有使用Swagger-UI 5.x版本且满足以下条件的场景：

1. 使用OpenAPI 3.x规范
2. 定义了content类型为application/json的查询参数
3. 参数schema为包含对象类型的数组

解决方案

这个问题已在Swagger-UI v5.15.2版本中修复。修复方案包括：

1. 修改swagger-js库的序列化逻辑，确保JSON内容类型的参数只被序列化一次
2. 正确处理数组中的对象元素，避免不必要的字符串转换

最佳实践

为避免类似问题，建议：

1. 对于复杂的查询参数，考虑使用POST请求和请求体而非查询参数
2. 明确指定参数的content-type为application/json
3. 定期更新Swagger-UI到最新版本
4. 测试生成的URL是否符合预期

总结

JSON查询参数的双重字符串化问题是Swagger-UI在处理复杂数据结构时的一个边界情况。理解这个问题的本质有助于开发者更好地设计API规范和使用Swagger工具链。随着Swagger-UI的持续更新，这类边界情况会得到更好的处理。