Swagger：从枚举中取一个或多个值

Posted 2023-02-19

【中文标题】Swagger：从枚举中取一个或多个值

【英文标题】：Swagger: take one or more values from enum

【发布时间】：2018-11-05 09:08:32

【问题描述】：

我正在编写一个 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)

【问题讨论】：

那么它是“一个或多个值”（例如，如果存在，必须至少有 1 个值）还是“无或 n 个值”（例如，可能没有值存在，如 ?sort )?

“没有或更多”。这就是存在allowEmptyValue: true 的原因。 ?sort=、?sort=field1、?sort=field1,field2 是有效路径。

【参考方案1】：

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

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

OpenAPI 2.0

参数定义如下所示。 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 3.x

OpenAPI 2.0 中的collectionFormat: csv 已替换为style: form + explode: false。 style: 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，因为在这种情况下，一个空数组实际上是一个空值。此外，allowEmptyValue 是自 OpenAPI 3.0.2 起使用的not recommended，“因为它将在未来的版本中删除。”

【讨论】：

谢谢，我试试看。

感谢您的出色回答。不幸的是，我与github.com/OpenAPITools/openapi-generator/issues/3345 发生了冲突：\

@Helen: swagger 是否支持带有键值对的枚举？