招摇过市：从枚举中获取一个或多个值

Question

我正在编写一个OpenAPI（Swagger）定义，其中一个查询参数可以取无，或N个值，如下所示：

/path?sort=field1,field2

如何在OpenAPI YAML中编写此内容？

我尝试了以下方法，但没有产生预期的结果：

- name: sort
  in: query
  schema:
    type: string
    enum: [field1,field2,field3]
  allowEmptyValue: true
  required: false
  description: Sort the results by attributes. (See http://jsonapi.org/format/1.1/#fetching-sorting)

Answer 1

包含以逗号分隔的值列表的查询参数定义为数组。如果这些值是预定义的，那么它是一个枚举数组。

默认情况下，一个数组可以有任意数量的项，这些项符合您的“无或多”要求。如果需要，您可以使用minItems和maxItems限制项目数量，并可以选择强制执行uniqueItems:true。

参数定义如下所示collectionFormat:csv表示值以逗号分隔，但这是默认格式，因此可以省略。

      parameters:
        - name: sort
          in: query
          type: array  # <-----
          items:
            type: string
            enum: [field1, field2, field3]
          collectionFormat: csv  # <-----
          required: false
          description: Sort the results by attributes. (See http://jsonapi.org/format/1.1/#fetching-sorting)

来自OpenAPI 2.0的格式： csv已被替换为样式： form爆炸： false。样式： form是查询参数的默认样式，因此可以省略。

      parameters:
        - name: sort
          in: query
          schema:
            type: array  # <-----
            items:
              type: string
              enum: [field1, field2, field3]
          required: false
          description: Sort the results by attributes. (See http://jsonapi.org/format/1.1/#fetching-sorting)
          explode: false  # <-----

我认为没有必要使用allowEmptyValue，因为在这种情况下，空数组实际上是一个空值。此外，自OpenAPI 3.0以来，不建议使用allowEmptyValue。2“因为它将在将来的版本中删除。”