Swagger / OpenAPI-используйте $ref для передачи повторно используемого определенного параметра
Допустим, у меня есть такой параметр, как limit. Этот используется повсюду, и это боль, чтобы изменить его везде, если мне нужно обновить его:
parameters:
- name: limit
in: query
description: Limits the number of returned results
required: false
type: number
format: int32
Могу ли я использовать $ref, чтобы определить это в другом месте и сделать его многоразовым? Я наткнулся на этот билет, который предполагает, что кто-то хочет изменить или улучшить функцию, но я не могу сказать, существует ли она уже сегодня или нет?
1 ответ:
Эта функция уже существует в Swagger 2.0. Связанный билет рассказывает о некоторых специфических механизмах его работы, которые не влияют на функциональность этой функции.
В объекте верхнего уровня (называемом Swagger Object) есть свойство
parameters, в котором можно определить повторно используемые параметры. Вы можете дать параметру любое имя и ссылаться на него из paths/specific operations. Параметры верхнего уровня являются всего лишь определениями и не применяются ко всем операциям в спецификации автоматически.Вы можете найти пример для этого здесь - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json - даже с предельным параметром.
В вашем случае, вы хотели бы сделать это:
# define a path with parameter reference /path: get: parameters: - $ref: "#/parameters/limitParam" # define reusable parameters: parameters: limitParam: name: limit in: query description: Limits the number of returned results required: false type: integer format: int32
Comments