java - Swagger 与 Spring-MVC 和自定义序列化器

Question

我正在尝试使用 Swagger 来记录基于 Spring-MVC 的 REST-API，但在让 Swagger 反射(reflect)自定义序列化器和反序列化器的使用时遇到问题。

因为 JSON 必须符合既定格式(设计得不是特别好)，并且我希望在 Java 类中拥有正确设计的 API 模型，所以我使用了 JsonSerializer 的一些自定义实现来生成 JSON 输出。当我在 Spring-MVC Controller 中启用带有注释的 Swagger 时，生成的文档会忽略自定义序列化器并描述模型，就好像它已使用默认 Jackson 设置进行序列化一样。到目前为止一切顺利，我并没有真正期望 Swagger 能够自动理解序列化器的实现。

然而，我所期望的(并且我在 Swagger 文档中找不到任何相关内容)是一种在模型类中的相关属性上使用 Swagger 注释来手动描述模型的方法。我是否遗漏了一些东西，或者 Swagger 真的不可能作为与自定义序列化器(或反序列化器)相关的文档工具吗？

编辑:Swagger 文档不是特别好，但我已经尝试使用 @ApiModelProperty 来处理偏离的属性。据我所知，它对生成的输出完全没有影响(使用 Swagger-SpringMVC 0.8.5 和 0.9.5 进行测试)。

Answer 1

您可以使用模型替代品，例如假设您有一项服务

@RequestMapping(value = { "/some-resource" }, method = POST, 
    consumes = APPLICATION_JSON_VALUE, produces = APPLICATION_JSON_VALUE)
@ResponseBody
public ResponseEntity<Void> 
    businessTypeEcho(@RequestBody CustomSerializableResource business) {
    return new CustomSerializableResource();
}

您可以设置类型替换规则，告诉 springmvc 如何在 swagger ui 中表示自定义可序列化类型。

@Bean //Don't forget the @Bean annotation
public SwaggerSpringMvcPlugin customImplementation(){
   return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
        .apiInfo(apiInfo())
        .directModelSubstitute(CustomSerializableResource.class, SubstitutedSerializableResource.class)
        .includePatterns(".*pet.*");
}

class SubstitutedSerializableResource {
    //getters and setters that describe what 
    //CustomSerializableResource should look like in the UI
}

不幸的是，这将创建一个运行时不使用的类型的并行宇宙。

更新:如果我正确理解您的评论，您正在使用它来格式化系统范围的类型，即 boolean 值到 Y/N 或日期到 mm/dd/yyyy 。 IMO，您可能正在寻找的是使用模型替代品(参见上面的示例)。

• 将 Date 替换为 String(这是 prescriptive guidance)。不幸的是，对于日期来说，传达预期格式的唯一选择是通过特定字段或属性的文本描述。
• 用您可以创建的枚举替换 Boolean，即表示您期望如何序列化对象的 YesNoEnum。这将为文档提供一组允许的值。

归根结底，这是为了文档而创建这些元类与标准化 API 模型以尽可能多地使用序列化原语之间的权衡。