Come rendere un campo in una definizione richiesta per alcune operazioni e non altre

Question

Sto scrivendo la mia definizione di swagger in yaml. Supponiamo che io abbia una definizione simile a questa.

paths: 
    /payloads: 
    post: 
     summary: create a payload 
     ... 
     parameters: 
     - in: body 
     name: payload 
     description: New payload 
     required: true 
     schema: 
      $ref: "#/definitions/payload" 
    put: 
     summary: update a payload 
     ... 
     parameters: 
     - in: body 
     name: payload 
     description: Updated existing payload 
     required: true 
     schema: 
      $ref: "#/definitions/payload" 
... 
definitions: 
    payload: 
    properties: 
     id: 
     type: string 
     someProperty: 
     type: string 
     ... 

C'è un modo che io possa indicare che la proprietà ID di un carico utile è necessario per l'operazione di PUT ed è opzionale (o non dovrebbe apparire a tutti) per l'operazione POST?

Answer 1

È necessario definire separatamente i modelli.

Tuttavia, sono disponibili opzioni per i casi di esclusione e differenza.

Se stai cercando di escludere, che è il caso facile, creare un modello con la proprietà esclusa, ad esempio ModelA. Quindi definire ModelB come ModelA più la proprietà aggiuntiva:

ModelB: 
    allOf: 
    - $ref: "#/definitions/ModelA" 
    - type: object 
     properties: 
     id: 
      type: string 

Se stai cercando di definire la differenza, seguire lo stesso metodo di cui sopra, ed escludere il id da ModelA. Quindi definire ModelB e ModelC come un'estensione ModelA e aggiungere la proprietà id a loro, ognuno con le proprie restrizioni. Intendiamoci, JSON Schema può permetterti di seguire l'esempio originale sopra riportato in alcuni casi per "sovrascrivere" una definizione. Tuttavia, dal momento che non è davvero eccessivo, e uno ha bisogno di capire meglio i concetti di JSON Schema per non commettere semplici errori, raccomanderei di seguire questo percorso per ora.