OpenAPI 中的“必需”到底是什么意思

Question

鉴于以下 OpenAPI 定义，以下哪些对象是有效的。只有 1. 或 1. 和 2.？

Person:
  required:
    - id
  type: object
  properties:
    id:
      type: string

1. {"id": ""}
2. {"id": null}
3. {}

这归结为“required = true”是指“非空值”还是“必须存在属性”的问题。

https://json-schema-validator.herokuapp.com/ 的 JSON 模式验证器表示 2. 无效，因为 null 不满足 type: string 约束。请注意，它不会抱怨因为id 为空，而是因为null 不是字符串。但这与 OpenAPI/Swagger 有多大关系？

Answer 1

OpenAPI Schema Objects 中的required 关键字取自JSON Schema，意思是：

如果[required] 数组中的每一项都是实例中属性的名称，则对象实例对该关键字有效。

换句话说，required 表示“属性必须存在”，无论其价值如何。属性值的type、format 等是单独的约束，它们与required 分开评估，但作为一个组合模式一起评估。

在你的例子中：

1. {"id": ""} 有效：

   • ✓ 验证 required
   • ✓ 值 "" 对 type: string 进行验证

2. {"id": null} 无效：

   • ✓ 验证 required
   • ✗ null 不会针对 type: string 进行验证（请参阅下面有关空值的说明）

3. {} 无效：

   • ✗ 不针对 required 进行验证

请注意，'null' 作为一种类型在 OpenAPI 2.0 中不受支持，而是 supported in OpenAPI 3.1，并且 3.0 具有 nullable 来处理空值。所以，{"id": null} 对这个 OpenAPI 3 架构有效：

Person:
  required:
    - id
  type: object
  properties:
    id:
      # OAS 3.1
      type: [string, 'null']

      # OAS 3.0
      # type: string
      # nullable: true