具有命名元素的数组的 Swagger 模型 [英] Swagger model for an array with named elements

问题描述

为 json 数组编写 swagger 模型对我来说似乎很简单，例如如果我有这个数组:

<预><代码>[{"name": "戴夫",数字":123},{"name": "玛丽",数字":456}]

我会为它编写以下 swagger 模型:

模式":{类型":数组"，项目": {"$ref": "学生"}}学生": {"id": "学生",必需的": [姓名"，数字"],特性": {姓名": {类型":字符串"},数字": {"类型": "整数",格式":int32"}}}

但是，我有以下几点:

<代码>{123":{姓名":戴夫"},456":{姓名":玛丽"}}

我如何为这个模型编写模型?

提前致谢.

解决方案

要描述请求模型，您需要使用 additionalProperties 属性.请注意，这在 Swagger 2.0 中可用，而在早期版本中不可用.

定义":{学生": {类型":对象"，必填":[姓名"]，特性": {姓名": {类型":字符串"}}},学生们": {类型":对象"，附加属性":{"$ref": "#/定义/学生"}}}

在上面您会看到 Student 模型，它当前包含名称"属性，但我假设您会向其中添加更多内容.从上面的示例中，名称"属性是必需的.

第二个模型是Students，它是一个包含地图(additionalProperties)的对象.每个属性都是 Student 类型(通过引用模型完成，但理论上可以内联定义).

您不能做的一件事是声明键(或属性名称)是整数或给定类型.patternedProperties 可以支持这点，而 Swagger 2.0 中没有.换句话说，没有限制密钥内容的技术方法.

Writing the swagger model for a json array seems pretty straightforward to me, e.g. if I had this array:

[
  {
    "name": "dave",
    "number": 123
  },
  {
    "name": "mary",
    "number": 456
  }
]

I would write the following swagger model for it:

"schema": {
  "type": "array",
  "items": {
    "$ref": "Student"
  }
}

"Student": {
  "id": "Student",
  "required": [
    "name",
    "number"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "number": {
      "type": "integer",
      "format": "int32"
    }
  }
}

However, I have the following:

{
  "123": {
    "name": "dave"
  },
  "456": {
    "name": "mary"
  }
}

How do I write the model for this one?

Thanks in advance.

解决方案

To describe the request model, you need to use the additionalProperties properties. Mind you, this is available in Swagger 2.0 and was not available in earlier versions.

"definitions": {
    "Student": {
        "type": "object",
        "required": [ "name" ],
        "properties": {
            "name": {
                "type": "string"
            }
        }
    },
    "Students": {
        "type": "object",
        "additionalProperties": {
            "$ref": "#/definitions/Student"
        }
    }
}

Above you see the Student model, which currently contains the "name" property, though I assume you'll add more to it. From your example above, the "name" property is required.

The second model is Students which is an object that contains a map (additionalProperties). Each property is of the Student type (done by referencing the model, but theoretically could have been defined inline).

The one thing you cannot do is declare that the key (or property name) is an integer or of a given type. That could have been supported with the patternedProperties which is not available in Swagger 2.0. In other words, there's no technical way of limiting the content of the key.

这篇关于具有命名元素的数组的 Swagger 模型的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！