如何将@ApiModelProperty数据类型设置为字符串以用于Swagger文档

Question

我正在使用Spring MVC（通过Spring Boot），并使用Swigger Spring MVC库集成了Swigger API文档。

我有一个类看起来像这样：

@ApiModel
public class CartItem {
    ...
    private Money listPrice; // joda money class

    @JsonSerialize(using = ToStringSerializer.class)
    @ApiModelProperty(required = true, dataType = "java.lang.String")
    public Money getListPrice() {
        return listPrice;
    }
    ...
}

因为我在这个字段中使用ToString序列化程序，所以它会返回listPrice。换句话说，JSON中的toString：

{
    "listPrice": "USD 10.50"
}

然而，swagger文档并不支持dataType=“java.lang.String”。它将响应模型显示为：

"CartItem": {
    "description": "",
    "id": "CartItem",
    "properties": {
        "listPrice": {
            "required": false,
            "type": "Money"
        }
    }
}

我已经尝试将@ApiModelProperty注释放在字段和方法上，在这两种情况下，必需字段都被尊重，但dataType字段被忽略。我还尝试为dataType使用"String"、"string"和"java.lang.String"，但都不起作用。

是我遗漏了什么，还是这只是Swigger spring mvc库中的一个bug？

Answer 1

@ApiModel
@JsonInclude(JsonInclude.Include.NON_EMPTY)
public class Model {
    @JsonDeserialize(using = LocalDateTimeDeserializer.class)
    @JsonSerialize(using = LocalDateTimeSerializer.class)
    @JsonProperty("myDate")
    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss")
    private final LocalDateTime myDateTime;

}

Answer 2

对于OpenApi（Swagger 3.0）和SpringDoc，可以使用以下全局配置。

static {
     SpringDocUtils.getConfig().replaceWithSchema(Money.class, new StringSchema());
}

Answer 3

原来dataType在当前版本的Swagger Spring MVC库中被完全忽略了。我在这里找到了关于它的简短讨论：

https://github.com/springfox/springfox/issues/602

看起来它可以包括在版本2一旦出来。

编辑：尽管版本2说它支持数据类型，但目前似乎不起作用。为了满足我的需求，更好的方法是使用直接模型替换配置文档设置，如下所示：

@Bean
public Docket swaggerSpringMvcPlugin() {
    return new Docket(DocumentationType.SWAGGER_2)
            .directModelSubstitute(Money.class, String.class);
}