在API Platform中配置OpenApi动态数组查询参数求助

你的问题出在数组参数的items配置逻辑错误，且缺少数组参数的传递格式定义，导致Swagger UI无法生成支持动态添加值的输入控件。以下是具体修正方案：

错误原因分析 #

你在items里嵌套了properties，但这个结构仅用于定义对象类型的数组元素；而你需要的是字符串类型的数组元素，直接指定type即可。另外，OpenAPI需要明确数组参数的传递风格，才能让Swagger UI支持动态添加值的交互。

修正后的代码 #

基于API Platform默认使用的OpenAPI 3.x规范，修正后的配置代码如下：

new Get(
    uriTemplate: '/v1/examples/query',
    openapi: new Model\Operation(
        summary: 'Query example',
        parameters: [
            [
                'name' => 'array',
                'in' => 'query',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        'type' => 'string' // 直接指定数组元素类型，无需嵌套properties
                    ]
                ],
                'description' => '字符串类型的数组参数',
                'style' => 'form', // 指定form风格的参数传递格式
                'explode' => true, // 启用拆分传递，生成array=val1&array=val2格式
                'allowReserved' => false
            ],
            [
                'name' => 'property',
                'in' => 'query',
                'schema' => [
                    'type' => 'string'
                ],
                'description' => '字符串参数'
            ]
        ]
    ),
    name: 'query_endpoint'
),

关键配置说明 #

• schema字段替代直接写type：OpenAPI 3.x要求参数的类型定义放在schema字段下，而非直接在参数根节点写type（后者是OpenAPI 2.x的写法）。
• items的正确写法：对于字符串、数字这类基本类型的数组元素，直接在items中声明type即可，properties仅用于定义对象的属性结构。
• style与explode的作用：style: form配合explode: true会让Swagger UI生成可动态添加多个值的输入框，参数传递格式为array=value1&array=value2，这是最通用的数组查询参数格式。

配置完成后，Swagger UI中的array参数将显示为支持动态添加值的交互控件，符合你的预期效果。

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