使用 Spring-MVC 和自定义序列化程序 Swagger

Question

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

因为 JSON 必须符合既定格式（设计得不是特别好），并且我希望在 Java 类中有一个设计合理的 API 模型，所以我使用了一些 JsonSerializer 的自定义实现来生成 JSON 输出。当我在 Spring-MVC 控制器中启用带有注释的 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
}

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

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

• 将Date 替换为String（这是prescriptive guidance）在日期的情况下，不幸的是，您只能通过特定字段或属性的文本描述来传达预期的格式。
• 用您可以创建的枚举替换Boolean，即YesNoEnum，它表示您希望如何序列化对象。这将为文档提供一组允许的值。

归根结底，在创建这些元类仅用于文档与标准化 API 模型以尽可能多地使用序列化原语之间进行权衡。