Swagger / OpenAPI - użyj $ ref, aby przekazać zdefiniowany parametr wielokrotnego użytku

Powiedzmy, że mam parametr taki jak limit. Ten jest używany w każdym miejscu i trudno jest go zmieniać wszędzie, jeśli muszę go zaktualizować:

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

Czy mogę użyć $ ref, aby zdefiniować to w innym miejscu i umożliwić jego ponowne użycie? Natknąłem się na ten bilet, który sugeruje, że ktoś chce zmienić lub ulepszyć funkcję, ale nie mogę powiedzieć, czy już istnieje dzisiaj, czy nie?

Ta funkcja już istnieje w Swagger 2.0. Połączony bilet mówi o niektórych jego mechanikach, które nie wpływają na funkcjonalność tej funkcji.

W obiekcie najwyższego poziomu (nazywanym obiektem Swagger) znajduje się parameterswłaściwość, w której można zdefiniować parametry wielokrotnego użytku. Możesz nadać parametrowi dowolną nazwę i odwoływać się do niego ze ścieżek / określonych operacji. Parametry najwyższego poziomu to tylko definicje i nie są automatycznie stosowane do wszystkich operacji w specyfikacji.

Przykład można znaleźć tutaj - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json - nawet z parametrem limit.

W twoim przypadku chciałbyś to zrobić:

# 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

Dla kompletności, oto jak by to wyglądało w 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