如何指示禁止在 swagger 文档中使用某个数字？

Question

我正在尝试在名为 myNumber 的 swagger 文档中指定一个属性，它可以是 [-1, 10] 范围内的任何整数，但 0 除外。这就是我目前所拥有的：

myNumber:
    type: integer
    description: You can use any number in [-1, 10] except 0.
    minimum: -1
    maximum: 10

如何明确禁止0？我在 openAPI 文档中没有找到这方面的任何规范。这甚至可能吗？

Answer 1

选项 1：枚举

如果可能值的列表很小，您可以将它们全部列出在 enum:

myNumber:
  type: integer
  description: You can use any number in [-1, 10] except 0.
  enum: [-1, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

这是最简单的解决方案，适用于 OpenAPI 2.0 和 3.x。

选项 2：一个

在 OpenAPI 3.x 中，您可以使用 oneOf 定义两个可能值范围：

myNumber:
  type: integer
  description: You can use any number in [-1, 10] except 0.
  oneOf:
    - enum: [-1]  # shorthand for `minimum: -1` + `maximum: -1`
    - minimum: 1
      maximum: 10

在 OpenAPI 3.1 中，您可以将 enum: [-1] 替换为 const: -1。

选项 3：不是

OpenAPI 3.x 还支持 not 定义实例不得满足的条件。例如，您排除值 0，如下所示：

myNumber:
  type: integer
  description: You can use any number in [-1, 10] except 0.
  minimum: -1
  maximum: 10
  not:
    enum: [0]

在 OpenAPI 3.1 中，您可以将 enum: [0] 替换为 const: 0。

但是，not 的实际工具支持可能会有所不同。

如何指示禁止在 swagger 文档中使用某个数字？

How does one indicate that a number is prohibited for use in swagger documentation?

swagger

openapi

选项 1：枚举

选项 2：一个

选项 3：不是