Swagger/OpenAPI - usa $ ref per passare un parametro definito riutilizzabile

Question

Diciamo che ho un parametro come limit. Questo viene utilizzato in tutto il luogo ed è un dolore di dover cambiare ovunque se ho bisogno di aggiornarlo:

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

Posso usare $ ref per definire questo altrove e renderlo riutilizzabile? Mi sono imbattuto nello this ticket che suggerisce che qualcuno voglia modificare o migliorare la funzione, ma non so se esiste già oggi o no?

Answer 1

Questa funzione esiste già in Swagger 2.0. Il ticket collegato parla di alcuni meccanismi specifici che non influiscono sulla funzionalità di questa funzione.

Nell'oggetto di livello superiore (noto come oggetto Swagger), esiste una proprietà parameters in cui è possibile definire i parametri riutilizzabili. È possibile assegnare al parametro qualsiasi nome e fare riferimento ad esso da percorsi/operazioni specifiche. I parametri di livello superiore sono solo definizioni e non vengono applicati automaticamente a tutte le operazioni nelle specifiche.

Qui trova un esempio: https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json - anche con un parametro limite.

Nel tuo caso, che ci si vuole fare questo:

# 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