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模型以尽可能使用序列化原语之间进行权衡。

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

1 个答案: