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

user_6509816 0
Viewed 335

I am trying to specify a property in my swagger documentation called myNumber, which can be any integer in [-1, 10] except 0. This is what I have so far:

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

How can I be explicit that 0 is prohibited? I haven't found any specification for this in the openAPI docs. Is this even possible?

swagger openapi
1 Answers

Option 1: enum

If the list of possible values is small, you can list them all in an 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]

This is the easiest solution and works in both OpenAPI 2.0 and 3.x.

Option 2: oneOf

In OpenAPI 3.x you can use oneOf to define two ranges of possible values:

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

In OpenAPI 3.1 you can replace enum: [-1] with const: -1.

Option 3: not

OpenAPI 3.x also supports not to define conditions that an instance must not meet. For example, you exclude the value 0 as follows:

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

In OpenAPI 3.1 you can replace enum: [0] with const: 0.

However, actual tooling support for not may vary.

user_1131160
Related