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


84

Скажімо, у мене є такий параметр, як limit. Цей звикає повсюдно, і боляче мусити його міняти скрізь, якщо мені потрібно оновити:

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

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

Відповіді:


132

Ця функція вже існує в Swagger 2.0. Пов’язаний квиток говорить про деякі його конкретні механіки, що не впливає на функціональність цієї функції.

У об’єкта верхнього рівня (іменований Об’єктом Сваггера) є 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

Чи можете ви це зробити і з параметрами шляху? Або лише параметри запиту?
brandonscript

Будь-який тип параметра, де б не використовувались параметри (на рівні шляху або самої операції). Визначення параметрів верхнього рівня використовує той самий об’єкт параметра, що й явно визначений для операцій.
Рон

6
Чи можна розширити параметр? Наприклад, одне і те ж визначення параметра може бути як in: pathв одному випадку, так і in: queryв іншому. Також в одному випадку може бути необов’язковим, а в іншому - обов’язковим.

8
Вам доведеться створити два окремі визначення для нього.
Рон

1
Чи можна зробити цілі аргументи запиту багаторазовими? тобто .: параметри: $ ref: "# / parameters / requestParams"
Конрад Галензовський,

28

Для повноти, ось як це могло б виглядати в 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
Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.