如何将 @ApiModelProperty 数据类型设置为 String 以获取 Swagger 文档

Question

我正在使用 Spring MVC（通过 Spring 引导）并使用 swagger-spring-mvc 库集成了 Swagger API 文档。

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

@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;
    }
    ...
}

由于我为此字段使用了 ToStringSerializer，它在 JSON 中返回 listPrice.toString，换句话说：

{
    "listPrice": "USD 10.50"
}

但是，swagger 文档不支持 dataType = "java.lang.String"。它将响应模型显示为：

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

我已经尝试将@ApiModelProperty 注释放在字段和方法上，在这两种情况下，required 字段都被尊重，但 dataType 字段被忽略。我也尝试过使用 "String"、"string" 和 "java.lang.String" 作为数据类型，但其中 none 有效。

我是不是遗漏了什么，或者这只是 swagger-spring-mvc 库中的一个错误？

Answer 1

原来 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);
}

Answer 2

@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 3

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

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

如何将 @ApiModelProperty 数据类型设置为 String 以获取 Swagger 文档

How to set @ApiModelProperty dataType to String for Swagger documentation

java

spring

spring-mvc

swagger