Как я могу описать сложную модель json в swagger

Я пытаюсь использовать Swagger для описания web-api, который я создаю. Проблема в том, что я не могу понять, как описать сложный объект json?

Например, как описать эти объекты:

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

Ответы

Ответ 1

Хорошо, поэтому, основываясь на комментариях выше, вам нужна следующая схема:

{
  "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"
            }
        }
    }
  }
}

Я сделал несколько предположений, чтобы сделать образец более сложным, чтобы помочь в будущем. Для объекта "user" я заявил, что поле "имя" является обязательным. Если, например, вам также нужен адрес, который будет обязательным, вы можете изменить определение на "required": [ "name", "address" ].

В основном мы используем подмножество json-схемы для описания моделей. Конечно, не все это знают, но это довольно просто узнать и использовать.

Для типа адреса вы можете видеть, что я также устанавливаю ограничение на два варианта - либо дома, либо офиса. Вы можете добавить что-нибудь в этот список или полностью удалить "перечисление", чтобы удалить это ограничение.

Когда "тип" свойства является "массивом", вам необходимо сопровождать его "элементами", которые объявляют внутренний тип массива. В этом случае я ссылался на другое определение, но это определение могло быть и встроенным. Обычно это проще поддерживать таким образом, особенно если вам нужно определение "адрес" самостоятельно или в других моделях.

В соответствии с запросом встроенная версия:

{
  "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"
              }
            }
          }
        }
      }
    }
  }
}