Swagger/OpenAPI-используйте $ref для передачи повторно определенного параметра

допустим, у меня есть такой параметр, как limit. Это один привыкает повсюду, и это боль, чтобы изменить его везде, если мне нужно обновить его:

parameters:
    - name: limit
      in: query
      description: Limits the number of returned results
      required: false
      type: number
      format: int32

могу ли я использовать $ref, чтобы определить это в другом месте и сделать его многоразовым? Я наткнулся этот билет что говорит о том, что кто-то хочет изменить или улучшить функцию, но я не могу сказать, существует ли она уже сегодня или нет?

1 63
swagger-ui swagger-2.0 openapi

1 ответ:

эта функция уже существует в Swagger 2.0. Связанный билет говорит о некоторых конкретных механиках этого, которые не влияют на функциональность этой функции.

в объекте верхнего уровня (называемом объектом Swagger) есть parameters свойство, в котором можно определить повторно используемые параметры. Вы можете дать параметру любое имя и ссылаться на него из путей/конкретных операций. Параметры верхнего уровня являются просто определениями и не применяются ко всем операциям в спецификации автоматически.

вы можете найти пример для него здесь - 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
108