Swagger Core 项目中 OpenAPI 3.1 参数类型生成问题解析

问题背景

在使用 Swagger Core 项目的 swagger-maven-plugin-jakarta 插件生成 OpenAPI 3.1 规范文件时，开发人员遇到了一个参数类型生成的异常问题。当启用 openAPI31 配置时，插件会将所有参数的类型生成为数组形式，即使这些参数实际上只需要单一类型。

问题现象

在生成的 OpenAPI 规范中，原本应该表示为简单类型的参数（如字符串类型）被错误地生成了包含单一元素的数组类型。例如：

"schema": {
  "type": ["string"]
}

而不是正确的：

"schema": {
  "type": "string"
}

问题影响

这种类型表示方式虽然从技术上讲符合 OpenAPI 3.1 规范（因为规范允许类型既可以是字符串也可以是字符串数组），但在实际使用中会导致以下问题：

1. Swagger UI 无法正确识别必填参数，即使参数已填写，仍会报错"Required field is not provided"
2. 生成的文档可读性降低，增加了不必要的复杂性
3. 可能与其他工具链不兼容

问题根源

经过分析，这个问题与插件的 sortOutput 配置有关。当开发者同时启用以下配置时会出现此问题：

1. openAPI31: true - 指定生成 OpenAPI 3.1 规范
2. sortOutput: true - 要求对输出结果进行排序

解决方案

目前有两种临时解决方案：

1. 禁用排序输出：将 sortOutput 设置为 false，这样可以避免类型被错误地生成为数组，但会失去输出排序功能

{
  "sortOutput": false
}

2. 等待官方修复：该问题已被官方确认并修复，将在下一个版本中发布

技术细节

OpenAPI 3.1 规范确实允许 type 字段接受字符串或字符串数组，这是为了支持更灵活的类型定义。然而，在大多数情况下，单一类型已经足够，将单一类型强制转换为数组类型虽然语法正确，但会带来不必要的复杂性和潜在的兼容性问题。

最佳实践建议

1. 在等待官方修复版本发布期间，建议暂时关闭 sortOutput 选项
2. 对于必须保持排序的情况，可以考虑在生成后使用外部工具对 OpenAPI 文档进行排序处理
3. 升级到修复版本后，可以安全地同时启用 openAPI31 和 sortOutput 选项

总结

这个问题展示了即使在遵循规范的情况下，实现细节的差异也可能导致实际使用中的问题。作为开发者，在遇到类似问题时，除了寻找临时解决方案外，还应该关注官方修复进度，及时升级到稳定版本。同时，这也提醒我们在使用工具链生成API文档时，需要仔细验证生成的输出是否符合预期。