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) есть свойство 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

Ответ 2

Для полноты, вот как это будет выглядеть в OpenAPI (aka 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

Ответ 3

Можете ли вы так же связать набор нескольких параметров? Т.е.

paths:
  /path:
    get:
      parameters:
        - $ref: "#/components/parameters/params"
components:
  parameters:
    params:
      - name: foo
        schema:
          type: string
      - name: bar
        schema:
          type: integer

Где params определяют несколько параметров, скажем, limit, offset, lastModifiedAfter... Я не могу заставить это работать, только с одним определенным paameter.