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

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

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

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

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

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

Вы можете найти здесь пример - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json - даже с параметром limit.

В вашем случае вам нужно сделать это:

# define a path with parameter reference
/path:
   get:
      parameters:
         - $ref: "#/parameters/limitParam"
         - $ref: "#/parameters/offsetParam"

# define reusable parameters:
parameters:
   limitParam:
      name: limit
      in: query
      description: Limits the number of returned results
      required: false
      type: integer
      format: int32
   offsetParam:
      name: offset
      in: query
      description: Offset from which start returned results
      required: false
      type: integer
      format: int32

Для полноты картины вот как это будет выглядеть в OpenAPI (также известном как swagger v3):

openapi: "3.0.0"
servers:
    - url: /v1
      description: local server

paths:
   /path:
      get:
         parameters:
            - $ref: "#/components/parameters/limitParam"

components:
   parameters:
      limitParam:
         name: limit
         in: query
         description: Limits the number of returned results
         required: false
         schema:
            type: integer
            minimum: 10
            default: 10
            multipleOf: 10 # matches 10, 20, ...
            format: int32