Swagger UI 不显示嵌入式 json 属性模型

Question

我正在使用 swagger 工具来记录我的基于 Jersey 的 REST API（我使用的 swaggerui 是在 2014 年 6 月下载的，不知道这个问题是否已在以后的版本中得到修复，但因为我对其进行了大量自定义代码，所以如果不花大量时间重新自定义它，我就无法下载最新版本）。

到目前为止，直到现在，我所有的传输对象都具有一级深度属性（没有嵌入的 pojo）。但是现在我添加了一些返回更复杂对象（两个深度级别）的休息路径，我发现 SwaggerUI 在嵌入对象时没有扩展 JSON 模型模式。

这是 swagger 文档的重要部分：

...
{
    "path": "/user/combo",
    "operations": [{
        "method": "POST",
        "summary": "Inserts a combo (user, address)",
        "notes": "Will insert a new user and a address definition in a single step",
        "type": "UserAndAddressWithIdSwaggerDto",
        "nickname": "insertCombo",
        "consumes": ["application/json"],
        "parameters": [{
            "name": "body",
            "description": "New user and address combo",
            "required": true,
            "type": "UserAndAddressWithIdSwaggerDto",
            "paramType": "body",
            "allowMultiple": false
        }],
        "responseMessages": [{
            "code": 200,
            "message": "OK",
            "responseModel": "UserAndAddressWithIdSwaggerDto"
        }]
    }]
}
...
"models": {
    "UserAndAddressWithIdSwaggerDto": {
        "id": "UserAndAddressWithIdSwaggerDto",
        "description": "",
        "required": ["user",
        "address"],
        "properties": {
            "user": {
                "$ref": "UserDto",
                "description": "User"
            },
            "address": {
                "$ref": "AddressDto",
                "description": "Address"
            }
        }
    },

    "UserDto": {
    "id": "UserDto",
    "properties": {
        "userId": {
            "type": "integer",
            "format": "int64"
        },
        "name": {
            "type": "string"
        },...
    },

    "AddressDto": {
    "id": "AddressDto",
    "properties": {
        "addressId": {
            "type": "integer",
            "format": "int64"
        },
        "street": {
            "type": "string"
        },...
    }

}
...

嵌入的对象是用户和地址，它们的模型正在正确创建，如 json 响应中所示。

但是打开 SwaggerUI 时我只能看到：

{
  "user": "UserDto",
  "address": "AddressDto"
}

但我应该看到类似：

{
  "user": {
    "userId": "integer",
    "name": "string",...
  },
  "address": {
    "addressId": "integer",
    "street": "string",...
  }
}

扩展内部属性的代码可能有问题，javascript 控制台没有显示任何错误，所以我认为这是一个错误。

Answer 1

我找到了解决办法，有一行代码需要修改才能正常工作：

在 swagger.js 文件中有一个 getSampleValue 函数，它对未定义进行条件检查：

SwaggerModelProperty.prototype.getSampleValue = function(modelsToIgnore) {
  var result;
  if ((this.refModel != null) && (modelsToIgnore[this.refModel.name] === 'undefined'))
...

我将相等检查更新为（删除引号）：

modelsToIgnore[this.refModel.name] === undefined

之后，SwaggerUI 能够显示嵌入的模型。