如何规范文档Laravel Purity风格的API请求参数？

Laravel Purity采用GET /api/posts?filters[field][operator]=value格式的请求参数，我尝试用以下OpenAPI配置对该参数进行文档化：

"parameters": [
    {   
        "description": "Filter data using the following syntax: filters[field][operator]=value",
        "schema": {
            "type": "string"
        },  
        "style": "deepObject",
        "allowReserved": true,
        "examples": {
            "name-contains": {
                "value": "[name][$contains]=test",
                "summary": "Search for forms where name contains string 'test'"
            },  
            "date-gt": {
                "value": "[created_at][$gt]=2024-01-01",
                "summary": "Search for forms created after '2024-01-01'"
            }   
        },  
        "name": "filters",
        "in": "query"
    }
]

但该配置生成的URL为GET /api/posts?filters=[field][operator]=value，多了一个多余的等号。请问是否存在无需枚举所有[field]和[operator]组合的文档化方法？

问题根源在于schema类型与deepObject样式不匹配：你把filters的schema定义成了字符串，但deepObject是用来处理嵌套对象结构的查询参数，两者搭配就会生成错误的URL格式。

不用枚举所有字段和操作符的正确配置方式如下：

核心思路 #

1. 将filters的schema定义为嵌套对象，用additionalProperties支持任意字段（无需枚举所有字段）
2. 操作符层级同样用additionalProperties（或指定允许的操作符），避免枚举所有Laravel Purity支持的操作符
3. 保留style: deepObject并设置explode: true，让OpenAPI自动生成正确的filters[field][operator]=value格式

完整配置示例 #

"parameters": [
    {
        "description": "过滤数据，语法：filters[field][operator]=value",
        "schema": {
            "type": "object",
            "additionalProperties": {
                "type": "object",
                "additionalProperties": {
                    "type": "string"
                },
                "description": "字段对应的操作符-值对"
            },
            "description": "过滤字段及对应的操作符-值组合"
        },
        "style": "deepObject",
        "explode": true,
        "allowReserved": true,
        "examples": {
            "name-contains": {
                "value": {
                    "name": {
                        "$contains": "test"
                    }
                },
                "summary": "搜索名称包含'test'的表单"
            },
            "date-gt": {
                "value": {
                    "created_at": {
                        "$gt": "2024-01-01"
                    }
                },
                "summary": "搜索2024-01-01之后创建的表单"
            }
        },
        "name": "filters",
        "in": "query"
    }
]

配置说明 #

• additionalProperties：外层允许任意字段名（对应[field]），内层允许任意操作符（对应[operator]），完全不用枚举所有可能的组合
• explode: true：配合deepObject样式，会将嵌套对象展开为filters[field][operator]=value的格式，不会出现多余的等号
• examples中的value改为对象结构：OpenAPI会自动将其转换为正确的查询字符串格式，无需手动写[name][$contains]=test这类字符串

可选：限制允许的操作符 #

如果不想开放所有操作符，可以把内层的additionalProperties换成properties，列出Laravel Purity支持的操作符，比如：

"additionalProperties": {
    "type": "object",
    "properties": {
        "$contains": { "type": "string" },
        "$gt": { "type": "string" },
        "$lt": { "type": "string" },
        "$eq": { "type": "string" }
        // 按需添加其他操作符
    },
    "description": "支持的操作符：$contains、$gt、$lt、$eq等"
}

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