Question

我正在尝试使用Swagger来描述我正在构建的web-api。问题是我无法理解如何描述复杂的json对象？

例如，如何描述这个对象：

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

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

我做了一些假设，使样本更加复杂，以便将来提供帮助。对于＆＃34;用户＆＃34;对象，我已宣布＆＃34; name＆＃34;字段是强制性的。例如，如果您还需要地址是强制性的，您可以将定义更改为＆＃34; required＆＃34;：[＆＃34; name＆＃34;，＆＃34; address＆＃34; ]

我们基本上使用json-schema的子集来描述模型。当然不是每个人都知道，但学习和使用起来相当简单。

对于地址类型，您可以看到我还将限制设置为两个选项 - 家庭或办公室。您可以向该列表添加任何内容，也可以删除＆＃34; enum＆＃34;完全删除那个约束。

当＆＃34;类型＆＃34;属性是＆＃34; array＆＃34;，你需要伴随＆＃34; items＆＃34;它声明了数组的内部类型。在这种情况下，我引用了另一个定义，但该定义也可以是内联的。通常这种方式更容易维护，特别是如果您需要＆＃34;地址＆＃34;单独定义或在其他模型中定义。

根据要求，内联版本：

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

如何在swagger中描述复杂的json模型

1 个答案: