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

问题背景

在 Swagger-UI 5.x 版本中，当开发者定义了一个接受对象数组的 JSON 查询参数时，系统会错误地对参数值进行双重 JSON 字符串化处理。这个问题在最新版本的 Swagger-UI 5.15.2 中已得到修复。

问题现象

当我们在 OpenAPI 3.1.0 规范中定义一个查询参数，该参数通过 content 属性指定为 application/json 类型，并且其 schema 是一个包含对象类型的数组时，Swagger-UI 生成的请求 URL 会出现异常。

具体表现为：本应只进行一次 JSON 字符串化的对象数组参数，实际上被处理了两次。例如，一个包含单个对象的数组 [{"a":"string","b":0}] 会被错误地转换为 ["{\"a\":\"string\",\"b\":0}"] 的形式，即先对对象进行字符串化，再将结果放入数组中再次字符串化。

技术分析

这个问题源于底层 swagger-js 库的处理逻辑。当处理查询参数时，系统应该：

1. 首先构建完整的 JSON 数据结构（在本例中是一个对象数组）
2. 对整个结构进行一次性的 JSON 字符串化
3. 最后进行 URL 编码

然而，在问题版本中，系统错误地对数组中的每个对象元素单独进行了字符串化，然后再对整个数组进行字符串化，导致了双重处理。

解决方案

开发团队通过两个关键修改解决了这个问题：

1. 在 swagger-js 中修复了参数序列化逻辑，确保对象数组只被正确处理一次
2. 在 Swagger-UI 中集成了这个修复，确保用户界面生成的请求符合预期

影响范围

这个问题主要影响以下使用场景：

• 使用 OpenAPI 3.x 规范
• 在查询参数中使用 content 属性定义 JSON 类型参数
• 参数类型为对象数组

对于大多数简单类型的参数或非查询位置的参数，不会受到此问题影响。

最佳实践

为了避免类似问题，建议开发者：

1. 保持 Swagger-UI 和相关依赖库的最新版本
2. 对于复杂的参数结构，进行充分的测试验证
3. 在定义 JSON 类型查询参数时，明确指定 content-type 为 application/json
4. 对于生产环境，考虑对生成的请求进行自动化测试

总结

这个问题的修复体现了 Swagger 生态系统的持续改进。通过底层库和用户界面组件的协同更新，确保了 API 文档工具生成的请求与实际业务需求保持一致。开发者现在可以放心使用对象数组作为 JSON 查询参数，而不用担心参数序列化异常的问题。