如何在招摇中描述复杂的 json 模型 [英] How can I describe complex json model in swagger

问题描述

我正在尝试使用 Swagger 来描述我正在构建的 web-api.问题是我看不懂如何描述复杂的json对象?

I'm trying to use Swagger to describe web-api I'm building. The problem is that I can't understand how to describe complex json object?

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

For example, how to describe this objects:

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

推荐答案

好的，所以根据上面的评论，您需要以下架构:

Okay, so based on the comments above, you want the following 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"
            }
        }
    }
  }
}

我做了一些假设，以使示例更复杂一些，以便将来提供帮助.对于用户"对象，我已经声明名称"字段是强制性的.例如，如果您还需要地址是强制性的，您可以将定义更改为必需":[名称"，地址"].

I've made a few assumptions to make the sample a bit more complicated, to help in the future. For the "user" object, I've declared that the "name" field is mandatory. If, for example, you also need the address to be mandatory, you can change the definition to "required": [ "name", "address" ].

我们基本上使用 json-schema 的一个子集来描述模型.当然不是每个人都知道它，但它很容易学习和使用.

We basically use a subset of json-schema to describe the models. Of course not everyone knows it, but it's fairly simple to learn and use.

对于您可以看到的地址类型，我还将限制设置为两个选项 - 家庭或办公室.您可以向该列表添加任何内容，或完全删除枚举"以删除该约束.

For the address type you can see I also set the limit to two options - either home or office. You can add anything to that list, or remove the "enum" entirely to remove that constraint.

当一个属性的类型"是数组"时，你需要伴随它的项目"，它声明了数组的内部类型.在这种情况下，我引用了另一个定义，但该定义也可能是内联的.这种方式通常更容易维护，尤其是当您需要单独或在其他模型中定义地址"时.

When the "type" of a property is "array", you need to accompany it with "items" which declares the internal type of the array. In this case, I referenced another definition, but that definition could have been inline as well. It's normally easier to maintain that way, especially if you need the "address" definition alone or within other models.

根据要求，内联版本:

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

这篇关于如何在招摇中描述复杂的 json 模型的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！