如何在 swagger 中描述复杂的 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"
            }
        }
    }
  }
}

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

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.

当一个属性的类型"为数组"时，需要在其后面加上items"来声明数组的内部类型.在这种情况下，我引用了另一个定义，但该定义也可以是内联的.以这种方式维护通常更容易，特别是如果您需要单独或在其他模型中的地址"定义.

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

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