Как определить необязательный параметр в пути с помощью swagger

В моей веб-службе REST есть функция, работающая с методом GET, и у нее есть два необязательных параметра.

Я попытался определить его в Swagger, но я обнаружил ошибку, Не допустимое определение параметра, после того, как я установил required как false.

Я узнал, что если я установил значение required как true, ошибка исчезнет. Вот пример моего кода Swagger.

...
paths:
  '/get/{param1}/{param2}':
    get:
      ...
      parameters:
      - name: param1
        in: path
        description: 'description regarding param1'
        required: false
        type: string
      - name: param2
        in: path
        description: 'description regarding param2'
        required: false
        type: string

Я не испытывал этого с параметрами в теле или теми, которые были в запросе. Я думаю, что эта проблема связана только с параметрами в пути. Я не мог найти никакого решения в спецификационных файлах swagger.

Есть ли другой способ определения необязательных параметров в Swagger или у меня есть какая-либо ошибка в моем коде?

Любая помощь будет оценена.

Ответы

Ответ 1

Учитывая, что параметр пути должен быть необходим в соответствии с спецификацией OpenAPI/Swagger, вы можете рассмотреть возможность добавления двух отдельных конечных точек со следующими путями:

  • /get/{param1}/{param2} (если предусмотрен параметр param2)
  • /get/{param1}/(если параметр param2 не указан)

Ответ 2

Это, вероятно, взорвется, потому что у вас не может быть базового параметра uri optional, только значения строки запроса (в случае URL-адреса).

Например:

  • GET/products/{id}/pricing? foo = bar
  • ** Если foo не является обязательным, то ваш параметр IN должен быть "запросом" не "путь"
  • ** Если {id} является необязательным, то что-то не так. {id} не может быть необязательным, поскольку он содержится в базовом uri.

Это должно работать:

{
"in":"query",
"required":false
}

Это не должно работать

{
"in":"path",
"required":false
}

измените свойство "in" на "запрос" вместо "путь", и оно должно работать.

Ответ 3

Ваш YAML терпит неудачу, потому что, как указано в спецификации:

Определяет, является ли этот параметр обязательным. Если параметр находится в "пути", это свойство требуется, и его значение ДОЛЖНО быть истинным.

Источник: http://swagger.io/specification/#parameterObject (см. таблицу фиксированных полей)