Kombinieren von Definitionen in Swagger-Dokumenten

Question

Ich dokumentiere eine API mit Swagger-Dokumenten. Ich habe mehrere Endpunkte, die einen gemeinsamen Satz von Basiseigenschaften haben. Ich würde gerne $ ref verwenden, um auf diesen Basissatz von Eigenschaften zu verweisen und diese Eigenschaften dann um zusätzliche Eigenschaften zu erweitern, die für jeden Endpunkt einzigartig sind. Ich stellte mir vor, dass es so etwas wie dies funktionieren, aber dies ist ungültig:

"properties": { 
    "$ref": "#/definitions/baseProperties", 
    unique_thing": { 
     "type": "string" 
    }, 
    "another_unique_thing": { 
     "type": "string" 
    } 
} 

Answer 1

Tat das Beispiel, das Sie hier geben ungültig ist, weil $ref kann nicht mit anderen Objekte im selben Objekt koexistieren. $ref ist eine JSON-Referenz und führt per Definition dazu, dass die anderen Eigenschaften ignoriert werden.

Von Ihrer Frage aus, ich nehme an, dass Sie nach der grundlegenden Zusammensetzung (eher als Vererbung) suchen. Dies ist mit dem Schlüsselwort allOf möglich.

Also, mit dem Beispiel, das Sie zur Verfügung gestellt, würden Sie so etwas wie dieses:

{ 
    "baseProperties": { 
    "type": "object", 
    "properties": { 
     ... 
    } 
    }, 
    "complexModel": { 
    "allOf": [ 
     { 
     "$ref": "#/definitions/baseProperties" 
     }, 
     { 
     "type": "object", 
     "properties": { 
      "unique_thing": { 
      "type": "string" 
      }, 
      "another_unique_thing": { 
      "type": "string" 
      } 
     } 
     } 
    ] 
    } 
} 

Sie auch die example in the spec überprüfen können.