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,但因为null它不是一个字符串.但是这对于OpenAPI/Swagger有多重要？

Answer 1

将required在OpenAPI的关键字的含义与同一JSON模式:

需要

如果对象实例的属性集包含此关键字的数组值中的所有元素,则该对象实例对此关键字有效.

最新的JSON Schema规范中的措辞(虽然它不是OpenAPI使用的那个)更清楚:

如果数组中的每个项都是实例中属性的名称,则对象实例对此关键字有效.

也就是说required,无论价值如何,都意味着"财产必须存在".的type,format该属性值的等是从单独评价单独的约束required,但合在一起作为组合模式.

在你的例子中:

1. {"id": ""} 已验证:

   • ✓验证 required
   • ✓值""验证type: string

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

   • ✓验证 required
   • ✗ null不验证type: string

3. {} 无效:

   • ✗不验证 required

请注意,nullOpenAPI不支持某种类型,但OpenAPI 3.0会添加该nullable属性以指示该值null.因此,{"id": null}将验证此OpenAPI 3.0架构:

Person:
  required:
    - id
  type: object
  properties:
    id:
      type: string
      nullable: true   # <----