关于Swagger中对象类型参数默认值的技术咨询

先贴出你的示例代码：

components:
  parameters:
    coordinates:
      in: query
      name: coordinates
      description: Test Obj Parameter
      schema:
        type: object
        properties:
          lat:
            type: number
            default: 0.0
          long:
            type: number
            default: 0.0
      required: false

paths:
  /my/path/:
    get:
      parameters:
        - $ref: "./common.yaml#/components/parameters/coordinates"

问题解答 #

1. 是否可以在路径的parameters部分定义default: [51.47, 0.0]？ #

从OpenAPI规范来说，这么做不符合定义。你的coordinates参数schema明确是object类型，数组格式的默认值和对象类型不匹配。虽然部分代码生成工具可能不会报错，但会破坏规范一致性，容易引发解析逻辑混乱。如果要给整个对象设默认值，应该用对象格式default: {"lat":51.47, "long":0.0}，不过结合你观察到的代码生成结果，当前工具大概率不会处理这个层级的默认值。

2. 若对象的所有成员字段均为可选，且参数本身也为可选，是否需要在路径的parameters中指定默认值？若不指定，用户调用接口时未传值，后端会收到坐标(0, 0)吗？ #

• 不需要在路径parameters层级指定默认值，你已经在schema的lat、long属性里分别定义了0.0的默认值，这就足够了。
• 后端是否能收到(0,0)，取决于后端框架的参数绑定逻辑和代码生成工具的实现：
  • 如果后端框架支持自动应用OpenAPI属性级的默认值，当用户完全不传coordinates参数时，框架会自动把lat和long设为各自的默认值0.0，最终得到(0,0)。
  • 结合你提到的代码生成现象，工具对对象级默认值（不管是数组还是对象格式）都没处理，但属性级默认值应该是生效的，这种情况下后端能拿到(0,0)。

关于你发现的代码生成现象补充 #

你提到设置对象级默认值或不设置时生成的代码完全相同，说明当前使用的代码生成工具不支持在参数层级设置对象类型的默认值，这类default配置会被直接忽略。而把成员字段设为必填时，工具生成isSet标志、设置器和反设置器，这是工具对必填字段的标准处理逻辑，用来判断该字段是否被用户显式传入。

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