webentwicklung-frage-antwort-db.com.de

Wie kann ich ein komplexes Json-Modell in Swagger beschreiben?

Ich versuche, Swagger zu verwenden, um die Web-API zu beschreiben, die ich baue. Das Problem ist, dass ich nicht verstehen kann, wie ein komplexes JSON-Objekt beschrieben wird?

Zum Beispiel, wie man diese Objekte beschreibt:

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

Okay, basierend auf den obigen Kommentaren 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 habe ein paar Annahmen getroffen, um die Stichprobe etwas komplizierter zu gestalten und in Zukunft zu helfen. Für das Objekt "user" habe ich angegeben, dass das Feld "name" obligatorisch ist. Soll die Adresse beispielsweise auch obligatorisch sein, können Sie die Definition in "Erforderlich" ändern: ["Name", "Adresse"].

Wir verwenden grundsätzlich eine Teilmenge des json-Schemas, um die Modelle zu beschreiben. Natürlich kennt es nicht jeder, aber es ist ziemlich einfach zu erlernen und anzuwenden.

Für den Adresstyp wird angezeigt, dass ich das Limit auf zwei Optionen festgelegt habe - zu Hause oder im Büro. Sie können dieser Liste alles hinzufügen oder die "Aufzählung" vollständig entfernen, um diese Einschränkung zu entfernen.

Wenn der "Typ" einer Eigenschaft "Array" ist, müssen Sie ihn mit "Elementen" versehen, die den internen Typ des Arrays deklarieren. In diesem Fall habe ich auf eine andere Definition verwiesen, aber diese Definition hätte auch inline sein können. Dies ist normalerweise einfacher, insbesondere wenn Sie die "Adress" -Definition 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"
              }
            }
          }
        }
      }
    }
  }
}
41
Ron