Combinare le definizioni nei documenti Swagger

Question

Sto documentando un'API con i documenti Swagger. Ho diversi endpoint che condividono un insieme comune di proprietà di base. Mi piacerebbe usare $ ref per riferirsi a quel set base di proprietà e quindi estendere quelle proprietà con proprietà aggiuntive che sono univoche per ciascun endpoint. Ho immaginato che avrebbe funzionato qualcosa di simile, ma questo non è valido:

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

Answer 1

Infatti, l'esempio si dà qui non è valida perché $ref non può coesistere con altre proprietà nella stesso oggetto. $ref è un riferimento JSON e, per definizione, le altre proprietà verranno ignorate.

Dalla tua domanda, presumo tu stia cercando la composizione di base (piuttosto che l'ereditarietà). Ciò è possibile utilizzando la parola chiave allOf.

Così, con l'esempio che hai fornito, si dovrebbe avere qualcosa di simile:

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

È anche possibile controllare la example in the spec.