如何在Swagger中引用另一个模型定义的ID

Question

假设我有User和UserType模型.我想在User模型中添加对UserType-ID的引用.swagger文档仅显示如何引用另一个(整个)模型,而不仅仅是其中一个属性.

所以我想知道它甚至可以仅引用另一个模型定义的属性.

"definitions": {
    "User": {
        "required": [
            "username",
            "typeId"
        ],
        "properties": {
            "id": {
                "type": "integer",
                "format": "int32"
            },
            "username": {
                "type": "string"
            },
            "typeId": {
                "$ref": "UserType.id" // ==> this doesn't work! and without
                                      // the ".id" part it would include all
                                      // the properties of UserType
            }
        }
    },
    "UserType": {
        "required": [
            "name"
        ],
        "properties": {
            "id": {
                "type": "integer",
                "format": "int32"
            },
            "name": {
                "type": "string"
            }
        }
    }
}

或者根本不可能,它应该只是:

"definitions": {
    "User": {
        ...
        "properties": {
            "typeId": {
                "type": "integer",
                "format": "int32"
            }
        }
    },
    ...
}

Answer 1

在Swagger 2.0中,模式对象不需要描述模型(与先前版本中的模型对象不同).例如,如果查看"body"参数,您将看到需要将Schema定义为类型,但该模式也可以表示基元和数组.

对于上面的问题(和评论),我建议使用以下结构:

"defintions": {
  "User": {
    "required": [
      "username",
      "typeId"
    ],
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32"
      },
      "username": {
        "type": "string"
      },
      "typeId": {
        "$ref": "#/definitions/TypeId"
      }
    }
  },
  "UserType": {
    "required": [
      "name"
    ],
    "properties": {
      "id": {
        "$ref": "#/definitions/TypeId"
      },
      "name": {
        "type": "string"
      }
    }
  },
  "TypeId": {
    "type": "integer",
    "format": "int32"
  }
}

TypeId现在已外部化,如果时间到了,您想要更改其定义,您可以在一个地方更改它.当然,您可能希望"description"在字段和模型中添加其他内容以更好地记录目的.