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

84

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?

swagger swagger-2.0 openapi brandonscript
źródło

Odpowiedzi:

132

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
Ron
źródło
Czy możesz to zrobić również z parametrami ścieżki? Czy tylko parametry zapytania?
brandonscript
Dowolny typ parametru, gdziekolwiek parametry są używane (na poziomie ścieżki lub samej operacji). Definicja parametru najwyższego poziomu używa tego samego obiektu parametru, co te jawnie zdefiniowane dla operacji.
Ron
6
Czy można rozszerzyć parametr? Na przykład ta sama definicja parametru może występować in: pathw jednym przypadku, a in: queryw innym. Może być również opcjonalny w jednym przypadku i wymagany w innym.
8
Musiałbyś utworzyć dla niego dwie oddzielne definicje.
Ron,
1
Czy jest możliwe, aby całe argumenty żądania były ponownie używane? tj .: parametry: $ ref: "# / parameters / requestParams"
Konrad Gałęzowski
28

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
Mediolan
źródło