OpenAPI 规范 - 如何指定接受一系列值的输入参数答案

【问题标题】：OpenAPI specifications - how to specify an input parameter that accepts a range of valuesOpenAPI 规范 - 如何指定接受一系列值的输入参数
【发布时间】：2021-05-20 11:32:26
【问题描述】：

使用 OpenAPI 3.0.3，我正在定义一个接受两个输入查询参数的 API 规范。

- 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

理想情况下，我想将两者结合起来，并且只有一个接受范围的参数，例如： [a,b] where a > 0 and b > a > 0。比如说：

- 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.

我知道minimum 和maximum。这将预设范围。我正在寻找作为输入提供的范围。这可以实现吗？

【问题讨论】：

相关：How to note a calculated default value in OAS3

标签： openapi specifications

【解决方案1】：

您可以将范围定义为 tuple（自 OpenAPI 3.1 起受支持）或 2 个元素的数组。

但是，没有办法拥有基于另一个值的动态minimum 属性。您需要在说明中提及此要求并验证后端的值。

# 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

【讨论】：

【解决方案2】：

我最终使用object 类型作为输入：

- 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

检查 Swagger UI，请求 URL 将解析为：

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

【讨论】：