如何用OpenAPI 3.0.x配置style:simple的对象路径参数验证

要实现你期望的http://test-api/users/role,admin,firstName,Alex路径格式（对应对象{"role":"admin","firstName":"Alex"}），核心是正确配置路径参数的style和explode属性，同时保证YAML语法规范。以下是可直接使用的正确配置：

openapi: 3.0.3
info:
  title: Test API
  version: 1.0.0
paths:
  /users/{userFilters}:
    get:
      summary: 获取指定筛选条件的用户
      parameters:
        - name: userFilters
          in: path
          required: true
          schema:
            type: object
            properties:
              role:
                type: string
              firstName:
                type: string
          style: simple
          explode: false
      responses:
        '200':
          description: 返回符合条件的用户列表

关键配置说明 #

• style: simple：明确指定采用simple风格序列化对象类型的路径参数，这是实现key,value,key,value格式的基础。
• explode: false：必须设置为false，因为simple风格下，explode=false会将对象的键值对按顺序用逗号拼接；若设为true，会生成key=value,key=value的格式，不符合你的需求。
• Schema定义：在schema中明确对象的属性类型，确保请求参数验证生效，避免因参数格式不符导致的错误。
• YAML语法规范：注意缩进（统一用2个空格）、冒号后加空格等细节，这是避免JSON解析错误的关键。

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