Swagger/OpenAPI - verwenden Sie $ ref, um einen wiederverwendbaren definierten Parameter zu übergeben

Question

Nehmen wir an, ich habe einen Parameter wie limit. Dieser wird überall verwendet, und es ist ein Schmerz, es zu haben überall zu ändern, wenn ich es aktualisieren müssen:

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

Kann ich $ ref verwenden, um dies an anderer Stelle zu definieren und wiederverwendbar machen? Ich bin auf this ticket gestoßen, was darauf hindeutet, dass jemand Features ändern oder verbessern möchte, aber ich kann nicht sagen, ob es schon heute existiert oder nicht?

Answer 1

Diese Funktion ist bereits in Swagger 2.0 vorhanden. Das verknüpfte Ticket spricht über einige spezielle Mechanismen, die die Funktionalität dieser Funktion nicht beeinträchtigen.

Im Objekt auf oberster Ebene (das als Swagger-Objekt bezeichnet wird) gibt es eine parameters-Eigenschaft, in der Sie wiederverwendbare Parameter definieren können. Sie können dem Parameter einen beliebigen Namen geben und aus Pfaden/spezifischen Operationen darauf verweisen. Die Parameter der obersten Ebene sind nur Definitionen und werden nicht automatisch auf alle Operationen in der Spezifikation angewendet.

Hier finden Sie ein Beispiel dafür - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json - auch mit einem Limit-Parameter.

In Ihrem Fall, würden Sie wollen, dies zu tun:

# 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