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

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

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

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


openapi swagger swagger-2.0
person brandonscript    schedule 18.11.2014    source источник

Ответы (2)


arrow_upward
140
arrow_downward

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

В объекте верхнего уровня (называемом Swagger Object) есть свойство 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"
         - $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
person Ron    schedule 19.11.2014
comment
Можете ли вы сделать это и с параметрами пути? Или только параметры запроса? - person brandonscript; 19.11.2014
comment
Любой тип параметра, где бы ни использовались параметры (на уровне пути или самой операции). Определение параметра верхнего уровня использует тот же объект параметра, что и явно определенные для операций. - person Ron; 19.11.2014
comment
Можно ли расширить параметр? Например, одно и то же определение параметра может быть in: path в одном случае и in: query в другом. Также может быть необязательным в одном случае и обязательным в другом. - person ; 28.09.2015
comment
Вам нужно будет создать для него два отдельных определения. - person Ron; 29.09.2015
comment
Не могли бы вы передать чванство? См. Здесь: stackoverflow.com/documentation/swagger/commit - person Stephan; 08.08.2016
comment
Можно ли сделать все аргументы запроса повторно используемыми? то есть: параметры: $ ref: # / parameters / requestParams - person Konrad Gałęzowski; 15.11.2016
comment
@ KonradGałęzowski - к сожалению, нет поддержки группировки параметров. - person Ron; 15.11.2016
comment
Можете ли вы сделать это с параметром, определенным в другом файле? - $ref: "common.yml#/parameters/limitParam"? Я думаю, у вас должно получиться, но это нарушает кодогенерацию ... - person Adam; 14.12.2017
comment
@ Адам технически да. Если есть проблема с генератором кода, отправьте заявку в репозиторий проекта. - person Ron; 03.01.2018

arrow_upward
35
arrow_downward

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