如何将 @ApiModelProperty dataType 设置为 String 以获取 Swagger 文档答案

【问题标题】：How to set @ApiModelProperty dataType to String for Swagger documentation如何将 @ApiModelProperty dataType 设置为 String 以获取 Swagger 文档
【发布时间】：2015-03-30 20:40:38
【问题描述】：

我正在使用 Spring MVC（通过 Spring Boot）并使用 swagger-spring-mvc 库集成了 Swagger 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;
    }
    ...
}

由于我为此字段使用了 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 字段。我也尝试过对 dataType 使用“String”、“string”和“java.lang.String”，但这些都不起作用。

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

【问题讨论】：

标签： java spring spring-mvc swagger

【解决方案1】：

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

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

看起来它可以包含在版本 2 中。

编辑：虽然第 2 版说它支持 dataType，但它目前似乎无法正常工作。满足我需求的更好方法是使用直接模型替换来配置文档设置，如下所示：

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

【讨论】：

您说得对，它现在在 2.0.x 中得到支持（在 2.0.0-SNAPSHOT 中可用），但有一些警告。数据类型必须是有效的包限定类。
谢谢@DilipKrishnan。我看到 github 上的文档也已更新以反映更改。
@DilipKrishnan 请将您的评论作为答案或将其合并到 nerdherd 的答案中 - 这是一条非常重要的信息

【解决方案2】：

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

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

【讨论】：

【解决方案3】：

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

}

【讨论】：

您应该添加一些解释，而不是仅仅复制和粘贴代码：)