从Swagger 1.2迁移至2.0后Swagger UI无法加载请求响应模型

问题场景 #

我正在从Swagger 1.2规范迁移到Swagger 2.0。此前在Swagger 1.2中，未使用@ApiModel和@ApiModelProperty注解也能生成模型Schema，但迁移后请求和响应的User Schema属性为空。

API配置代码 #

@ApiOperation(value = "Get user", notes = "get user", response = User.class)
@ApiResponses(value = { @ApiResponse(code = RestConstant.STATUS_CODE_400, message = "Invalid User Input"),
        @ApiResponse(code = RestConstant.STATUS_CODE_500, message = "Internal Server Error") })
@Override
@GZIP
@Path("/{number}")
@PUT
public Response getUser( @ApiParam(value = "Profile object with hostname", required = true) User user,
        @PathParam("accountNumber") String number) {
    // 方法实现
}

生成的Swagger定义中User Schema #

"User": {
  "type": "object",
  "properties": {

  },
  "xml": {
    "name": "user"
  }
}

Swagger UI配置 #

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="description" content="SwaggerUI" />
  <title>SwaggerUI</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>
<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-standalone-preset.js" crossorigin></script>
<script>
  window.onload = () => {
    window.ui = SwaggerUIBundle({
      url: 'restservices/swagger.json',
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ],
      layout: "StandaloneLayout",
    });
  };
</script>
</body>
</html>

我想了解：现在是否必须使用@ApiModel和@ApiModelProperty注解？另外，我的模型类是从xsd文件生成的，能否提供相关的注解文档？

解答 #

1. 是否必须使用@ApiModel和@ApiModelProperty注解？ #

Swagger 2.0对应的swagger-core工具链（通常是1.5.x及以上版本）和Swagger 1.2的机制不同：

• Swagger 1.2默认会通过反射自动识别POJO的字段并生成Schema；
• Swagger 2.0默认不会自动扫描POJO字段，需要显式标记或者配置自动扫描规则。

所以不是绝对必须，但如果不使用这两个注解，你需要额外配置swagger-core来启用自动扫描POJO字段（比如通过配置SwaggerConfig开启反射扫描），不过这种方式在复杂场景下（比如嵌套对象、自定义序列化）容易出现识别不全的问题。

为了稳定生成完整且符合预期的Schema，建议显式使用@ApiModel和@ApiModelProperty注解。

2. XSD生成类的注解处理 #

如果模型类是从XSD文件生成的（比如用JAXB的xjc工具），可以通过以下两种方式添加Swagger注解：

• 方式一：使用XJC插件自动生成注解：使用支持Swagger注解的XJC插件（如swagger-jaxrs-maven-plugin），在maven编译阶段生成Java类时，自动给类添加@ApiModel、给字段添加@ApiModelProperty。只需要在pom.xml中配置插件参数即可，无需手动修改生成的代码。
• 方式二：手动扩展生成类：如果无法修改生成流程，可以创建继承自生成类的子类，在子类中添加Swagger注解；或者使用Jackson的@JsonProperty等注解配合Swagger的Jackson集成，让Swagger通过Jackson的元数据识别字段，但这种方式兼容性不如原生Swagger注解。

3. 核心注解文档 #

@ApiModel

• 作用：标记类为Swagger模型对象，用于生成对应的Schema。
• 常用属性：
  • value：自定义模型名称，默认使用类名。
  • description：模型的描述文本。
  • parent：指定父类，继承父类的字段Schema。

@ApiModelProperty

• 作用：标记POJO字段，定义该字段在Swagger Schema中的属性。
• 常用属性：
  • value：字段的描述文本。
  • name：Schema中显示的字段名称，默认使用Java字段名。
  • required：标记字段是否为必填项，对应Schema中的required数组。
  • dataType：指定字段的数据类型（如"String"、"Integer"），默认根据Java字段类型自动推断。
  • example：字段的示例值，用于Swagger UI展示。
  • hidden：设置为true时，该字段不会出现在生成的Schema中。

内容的提问来源于stack exchange，提问作者Mehul Parmar