Modell mit anderen erforderlichen Eigenschaften erneut verwenden

Question

Ich habe einen Pfad, der komplexe Modelle mit fast identischen Eigenschaften für jede HTTP-Methode verwendet. Das Problem ist, dass ich einige erforderlichen Eigenschaften für die Anforderung von PUT und POST definieren möchte, während keine Eigenschaften in GET-Antwort erforderlich sind (da der Server immer alle Eigenschaften zurückgibt und es an anderer Stelle in der Dokumentation erwähnt wird).

Ich habe eine einfache Cat-API erstellt, um zu demonstrieren, was ich ausprobiert habe. Die Idee ist, dass für die GET-Antwort das Antwortmodell nicht wie erforderlich markiert ist, sondern dass die Anforderung von PUT einen Namen für die Katze haben muss.

swagger: "2.0" 

info: 
    title: "Cat API" 
    version: 1.0.0 

paths: 
    /cats/{id}: 
    parameters: 
     - name: id 
     in: path 
     required: true 
     type: integer 
    get: 
     responses: 
     200: 
      description: Return a cat 
      schema: 
      $ref: "#/definitions/GetCat" 
    put: 
     parameters: 
     - name: cat 
      in: body 
      required: true 
      schema: 
      $ref: "#/definitions/PutCat" 
     responses: 
     204: 
      description: Cat edited 

definitions: 
    Cat: 
    type: object 
    properties: 
     name: 
     type: string 
    GetCat: 
    allOf: 
     - $ref: "#/definitions/Cat" 
    properties: 
     id: 
     type: integer 
    PutCat: 
    type: object 
    required: 
     - name 
    properties: 
     $ref: "#/definitions/Cat/properties" 

Swagger Editor sagt, dass dies eine gültige Spezifikation, aber name wird als für beide erforderlich GET und PUT. Das Gleiche gilt für Swagger UI.

Ich habe auch versucht die folgende Version von PutCat:

PutCat: 
    type: object 
    required: 
    - name 
    allOf: 
    - $ref: "#/definitions/Cat" 

Aber jetzt ist alles optional.

Ich kann das nicht herausfinden. Gibt es eine Möglichkeit, dies richtig zu machen?

EDIT:

Wie Helen richtig erwähnt, kann ich readOnly Sie mit diesem besonderen Fall mit GET und PUT zu lösen.

Aber sagen wir, ich füge breed Eigenschaft hinzu, die (zusätzlich zu der name Eigenschaft) für PUT bereitgestellt werden muss. Dann füge ich die PATCH-Methode hinzu, die verwendet werden kann, um entweder breed oder name zu aktualisieren, während die andere unverändert bleibt, und ich möchte keine davon wie erforderlich einstellen.

Answer 1

In Ihrem Beispiel können Sie ein einzelnes Modell für GET und POST/PUT verwenden, wobei die Eigenschaften nur in der als readOnly gekennzeichneten GET-Antwort verwendet werden. Von den spec:

readOnly

die Eigenschaft als "read only" erklärt. Dies bedeutet, dass es als Teil einer Antwort gesendet werden kann, aber nicht als Teil der Anfrage gesendet werden soll. Eigenschaften, die als readOnly markiert sind, SOLLEN sich NICHT in der erforderlichen Liste des definierten Schemas befinden. Der Standardwert ist false.

Die Spezifikation würde wie folgt aussehen:

get: 
     responses: 
     200: 
      description: Return a cat 
      schema: 
      $ref: "#/definitions/Cat" 
    put: 
     parameters: 
     - name: cat 
      in: body 
      required: true 
      schema: 
      $ref: "#/definitions/Cat" 
     responses: 
     204: 
      description: Cat edited 

definitions: 
    Cat: 
    properties: 
     id: 
     type: integer 
     readOnly: true 
     name: 
     type: string 
     breed: 
     type: string 
    required: 
     - name 
     - breed 

Dies bedeutet, dass Sie die name und breed PUT muss:

und GET /cats/{id} müssen die name und breed zurückkehren und zurückgeben kann auch die id

{ 
    "name": "Puss in Boots", 
    "breed": "whatever" 
} 

:

{ 
    "name": "Puss in Boots", 
    "breed": "whatever", 
    "id": 5 
}