如何在OpenAPI描述中定义一个可以是电子邮件格式或空字符串的属性（swagger）

Question

我有一个电子邮件字段，用户将其作为 POST/PUT API 的一部分发送。我想使用 OpenAPI 规范验证电子邮件是否采用正确的电子邮件格式（如果存在）。如果它作为空字符串给出，我不想进行检查。我怎样才能实现这个目标。

我知道如何接受空值

email:
    type: string
    format: email
    nullable: true

但我想接受空字符串，而不是 null。我们可以为此做些什么吗

email:
  type: string
  anyOf:
    format: email
    format: empty

Answer 1

从技术上讲，

format

不用于验证目的。这就是 JSON Schema 世界中所谓的

annotation

，OpenAPI 正是基于它。它只是一个信息属性。一些验证器或工具将使用此属性来增强验证结果，但这不是必需的。

在您的情况下，从 JSON 模式验证的角度来看，任何字符串值在技术上都是有效的，包括空字符串。

email:
  type: string
  format: email
  nullable: false

Answer 2

您使用

oneOf

的想法是正确的。你可以这样做：

email:
  oneOf:
    - type: string
      format: email
    - type: string
      minLength: 0
      maxLength: 0

这将允许空字符串或有效的电子邮件，但不允许为空。