Wie kann ich komplexe JSON-Modell in Swagger

Question

beschreiben Ich versuche Swagger zu beschreiben, Web-API, die ich baue. Das Problem ist, dass ich nicht verstehe, wie komplexe JSON-Objekt zu beschreiben?

Zum Beispiel, wie diese beschreiben Objekte:

{ 
    name: "Jhon", 
    address: [ 
    { 
     type: "home", 
     line1: "1st street" 
    }, 
    { 
     type: "office", 
     line1: "2nd street" 
    } 
    ] 
} 

Answer 1

Okay, so auf der Grundlage der obigen Ausführungen, möchten Sie das folgende Schema:

{ 
    "definitions": { 
    "user": { 
     "type": "object", 
     "required": [ "name" ], 
     "properties": { 
     "name": { 
      "type": "string" 
     }, 
     "address": { 
      "type": "array", 
      "items": { 
      "$ref": "#/definitions/address" 
      } 
     } 
     } 
    }, 
    "address": { 
     "type": "object", 
     "properties": { 
      "type": { 
       "type": "string", 
       "enum": [ "home", "office" ] 
      }, 
      "line1": { 
       "type": "string" 
      } 
     } 
    } 
    } 
} 

ich einige Annahmen gemacht haben Machen Sie die Probe ein bisschen komplizierter, um in der Zukunft zu helfen. Für das Objekt "user" habe ich erklärt, dass das Feld "name" obligatorisch ist. Wenn Sie zum Beispiel die Adresse auch zwingend benötigen, können Sie die Definition in "erforderlich" ändern: ["Name", "Adresse"].

Wir verwenden im Grunde eine Teilmenge von JSON-Schema, um die Modelle zu beschreiben. Natürlich weiß es nicht jeder, aber es ist ziemlich einfach zu lernen und zu benutzen.

Für den Adresstyp können Sie sehen, dass ich auch das Limit auf zwei Optionen festlegen - entweder zu Hause oder im Büro. Sie können dieser Liste beliebige Elemente hinzufügen oder die "enum" vollständig entfernen, um diese Einschränkung zu entfernen.

Wenn der "Typ" einer Eigenschaft "Array" ist, müssen Sie es mit "Elemente", die den internen Typ des Arrays deklariert begleiten. In diesem Fall habe ich auf eine andere Definition verwiesen, aber diese Definition könnte auch Inline sein. Normalerweise ist es einfacher, dies zu tun, besonders wenn Sie die Definition "Adresse" alleine oder in anderen Modellen benötigen.

Wie gewünscht, die Inline-Version:

{ 
    "definitions": { 
    "user": { 
     "type": "object", 
     "required": [ 
     "name" 
     ], 
     "properties": { 
     "name": { 
      "type": "string" 
     }, 
     "address": { 
      "type": "array", 
      "items": { 
      "type": "object", 
      "properties": { 
       "type": { 
       "type": "string", 
       "enum": [ 
        "home", 
        "office" 
       ] 
       }, 
       "line1": { 
       "type": "string" 
       } 
      } 
      } 
     } 
     } 
    } 
    } 
}