Swagger如何定义同时支持两种传参格式的数组查询参数

OpenAPI 3.0及以上版本可以直接通过参数schema的oneOf规则同时兼容两种传参格式，示例配置如下：

paths:
  /users:
    get:
      parameters:
        - name: id
          in: query
          description: 用户ID，支持多同名参数拼接或逗号分隔传参
          schema:
            oneOf:
              # 匹配逗号分隔的传参格式：id=1,2,3
              - type: array
                items:
                  type: integer
                style: form
                explode: false
              # 匹配多参数同名的传参格式：id=1&id=2&id=3
              - type: array
                items:
                  type: integer
                style: form
                explode: true

注意事项 #

• 如果你还在使用Swagger 2.0（OpenAPI 2.0），该版本原生不支持同时指定两种explode规则，可以在参数描述里明确标注支持两种传参格式，然后后端自行实现参数解析逻辑即可。
• Swagger UI 4.x及以上版本已经支持识别该配置，会在接口文档中同时展示两种传参的示例。
• 不要只改文档配置，还要同步调整后端的参数解析器，确保两种格式的入参都能被正常识别转换为数组，比如SpringBoot项目可以自定义参数解析器处理该场景，FastAPI可以通过自定义依赖实现兼容解析。

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