Swagger: взять одно или несколько значений из перечисления

Я пишу определение OpenAPI (Swagger), в котором параметр запроса не может принимать значения N или 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)?

— 26.05.2018 15:03

Это «ничего или более». Вот почему присутствует allowEmptyValue: true. ?sort=, ?sort=field1, ?sort=field1,field2 - допустимый путь.

— 27.05.2018 08:57

swagger swagger-2.0 openapi

26.05.2018 01:56

Документирование API с помощью Swagger на Springboot

В предыдущей статье мы уже узнали, как создать Rest API с помощью Springboot и MySql .

6 173

Перейти к ответу Данный вопрос помечен как решенный

Ответы 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.0

collectionFormat: csv из OpenAPI 2.0 был заменен на 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, «поскольку он будет удален в будущей версии».

Спасибо, я попробую.

— 29.05.2018 10:22

Спасибо за отличный ответ. К сожалению, мне не нравится github.com/OpenAPITools/openapi-generator/issues/3345: \

— 09.12.2019 11:05

@Helen: Поддерживает ли swagger перечисления с парами ключ-значение?

— 04.03.2021 18:06

28.05.2018 21:23