OpenAPI specifications - how to specify an input parameter that accepts a range of values

Question

Using OpenAPI 3.0.3, I am defining an API spec which accepts two input query parameters.

- name: land_area_llimit
  in: query
  description: Lower limit for land area comparison
  required: false
  schema:
      type: integer
- name: land_area_ulimit
  in: query
  description: Upper limit for land area comparison
  required: false
  schema:
      type: integer

Ideally, I would like to combine the two and have just one parameter, that accepts a range, like: [a,b] where a > 0 and b > a > 0. Say, something like:

- name: land_area
  in: query
  description: lower and upper bounds for land area comparison
  required: false
  schema:
      type: range     
  ## With some way to specify that this parameter accepts a lower bound and an upper bound. 

I am aware of the minimum and maximum. That will preset the ranges. I am looking for the ranges to be provided as input. Can this be achieved?

Answer 1

You can define the range as a tuple (supported since OpenAPI 3.1) or as an array of 2 elements.

However, there's no way to have a dynamic minimum attribute that's based on another value. You'll need to mention this requirement in the description and verify the values on the backend.

# openapi: 3.1.0

- name: land_area
  in: query
  description: Lower and upper bounds for land area comparison
  required: false
  schema:
    type: array
    prefixItems:
    - type: integer
      description: Lower bound for land area comparison
    - type: integer
      description: >-
        Upper bound for land area comparison.
        Must be greater than the lower bound.
    minItems: 2
    additionalItems: false

Answer 2

I ended up using an object type for the input:

- name: land_area
  in: query
  description: Land area ranges for comparison (in sqft). lower_bound < upper_bound. Return 400 otherwise.
  required: false
  schema:
    type: object
      properties:
        land_area_lower_bound:
          type: integer
        land_area_upper_bound:
          type: integer

Checking in Swagger UI, the request URL will resolve to something like:

http://<url>/<api>?land_area_lower_bound=1234&land_area_upper_bound=3456