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

Question

Załóżmy, że mam parametr taki jak limit. To jeden przyzwyczaja się wszędzie i jest to ból musiał zmienić go wszędzie, jeśli trzeba go aktualizować:

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

mogę użyć $ ref zdefiniować to gdzie indziej i uczynić go do wielokrotnego użytku? Natrafiłem na this ticket sugerujące, że ktoś chce zmienić lub ulepszyć funkcję, ale nie mogę stwierdzić, czy już istnieje, czy nie?

Answer 1

Ta funkcja już istnieje w Swagger 2.0. Połączony bilet mówi o pewnej specyficznej jego mechanice, która nie wpływa na funkcjonalność tej funkcji.

W obiekcie najwyższego poziomu (określanym jako Obiekt Swagger) istnieje właściwość parameters, w której można zdefiniować parametry do ponownego użycia. Możesz nadać parametrowi dowolną nazwę i odnosić się do niej ze ścieżek/konkretnych operacji. Parametry najwyższego poziomu są tylko definicjami i nie są automatycznie stosowane do wszystkich operacji w specyfikacji.

Możesz znaleźć tutaj przykład - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json - nawet z parametrem limitu.

W twoim przypadku, że chcesz to zrobić:

# define a path with parameter reference 
/path: 
    get: 
     parameters: 
     - $ref: "#/parameters/limitParam" 

# define reusable parameters: 
parameters: 
    limitParam: 
     name: limit 
     in: query 
     description: Limits the number of returned results 
     required: false 
     type: number 
     format: int32