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

84

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

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

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

swagger swagger-2.0 openapi брендонскрипт
источник

Ответы:

134

Эта функция уже существует в 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
Рон
источник
Можно ли это сделать и с параметрами пути? Или только параметры запроса?
brandonscript
Любой тип параметра, где бы ни использовались параметры (на уровне пути или самой операции). Определение параметра верхнего уровня использует тот же объект параметра, что и явно определенные для операций.
Рон
6
Можно ли расширить параметр? Например, одно и то же определение параметра может быть in: pathв одном случае и in: queryв другом. Также может быть необязательным в одном случае и обязательным в другом.
8
Вам нужно будет создать для него два отдельных определения.
Рон
2
Можно ли сделать все аргументы запроса повторно используемыми? например: параметры: $ ref: "# / parameters / requestParams"
Конрад Галензовски
31

Для полноты картины вот как это будет выглядеть в 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
Милан
источник