招摇 @ApiModelProperty List<String> 属性的示例值答案

【问题标题】：swagger @ApiModelProperty example value for List<String> property招摇 @ApiModelProperty List<String> 属性的示例值
【发布时间】：2016-12-06 06:23:26
【问题描述】：

我有一个班级，其中有一个属性是List<String>

public class MyClass {
    ....
    @ApiModelProperty(position = 2)
    private List<String> productIdentifiers;
    ....
}

此代码生成的示例值如下：

{
  "customerId": "1001",
  "productIdentifiers": [
    "string"
  ],
  "statuses": [
    "NEW"
  ]
}

此处显示的示例值无效。我预期的示例值应该是这样的：

{
  "customerId": "1001",
  "productIdentifiers": [
    "PRD1",
    "PRD2",
    "PRD3"
  ],
  "statuses": [
    "NEW"
  ]
}

我尝试传递如下示例属性，但它没有生成正确的值：

@ApiModelProperty(position = 2, example = "PRD1, PRD2, PRD3")
// This generates -> "productIdentifiers": "PRD1, PRD2, PRD3" // Its not json array

@ApiModelProperty(position = 2, example = "[\"PRD1\", \"PRD2\", \"PRD3\"]")
// This generates -> "productIdentifiers": "[\"PRD1\", \"PRD2\", \"PRD3\"]" // Its too not json array

有什么方法可以为 List 属性生成正确的示例值吗？

更新：

我已经尝试过@nullpointer 和@Zeeshan Arif 建议的解决方案

@ApiModelProperty(position = 2, dataType="List", example = "PRD1, PRD2, PRD3")
private List<String> productIdentifiers;
//This generates -> `"productIdentifiers": "PRD1, PRD2, PRD3"`

更新 2：

尝试了以下没有产生正确响应的方法

@ApiModelProperty(position = 2, dataType="java.util.List<String>", example = "PRD1, PRD2, PRD3")
// This generates -> "productIdentifiers": "PRD1, PRD2, PRD3"


@ApiModelProperty(position = 2, dataType="String[]", example = "PRD1, PRD2, PRD3")
// This generates -> "productIdentifiers": "PRD1, PRD2, PRD3"

我对 swagger jar 的 maven 依赖项是：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
    <exclusions>
        <exclusion>
            <artifactId>mapstruct</artifactId>
            <groupId>org.mapstruct</groupId>
        </exclusion>
    </exclusions>
</dependency>

更新 github ticket for this issue

【问题讨论】：

@Anil Bharadia 你对dataType=List<String>" 有什么回应？也只是为了精确测试，您使用的是什么招摇版本/依赖项？
@nullpointer 我的所有尝试都得到“PRD1, PRD2, PRD3”。
@AnilBharadia 你解决了吗？我正在为同样的问题苦苦挣扎，现在在 Springfox 3.0.0 中，none 提供的答案对我不起作用。另见github.com/swagger-api/swagger-core/issues/1855 和github.com/swagger-api/swagger-core/issues/3863
@HonzaZidek 我从事那个项目已经很久了。据我记得，我无法解决这个问题。我已经尝试了一些答案，但没有尝试最近提供的答案。我将尝试创建一个示例项目来测试新答案是否有效。

标签： java swagger springfox

【解决方案1】：

我设法让它工作，生成一个字符串列表。

在 springfox 2 的 ApiModelProperty 中，编写您的示例如下：

example = "[\"AddLine1\",\"AddLine2\",\"AddLine3\",\"AddLine4\"]"

这是我的例子：

@ApiModelProperty(value = "Address", name = "addLines", 
    example = "[\"AddLine1\",\"AddLine2\",\"AddLine3\",\"AddLine4\"]")

当我渲染 swagger 页面时，我得到以下输出：

"addLines": [
      "AddLine1",
      "AddLine2",
      "AddLine3",
      "AddLine4"
    ],

【讨论】：

不幸的是，对于 Integer 或 Long 值的列表/集，这同样不起作用
@MattByrne，是的，这行得通。甜的！我原来的评论不再有效，所以删除它以避免误导任何人。
适用于 Springfox v3.0.0。
它不适用于 Springfox 3.0.0，我刚刚测试过。不生成 JSON 数组 [...]，而是生成字符串 "[...]"。

【解决方案2】：

TLDR：Swagger-API 的贡献者之一已经致力于此功能，以便在版本 3.0.0 中添加此功能，但尚不确定何时发布。目前它位于 Swagger-API GitHub 的 feature/3.0.0-rc2 分支上

我已经与 Swagger 合作了将近两个月，随着我们项目的进展，出现了这样的问题。现在我做了一些研究，并在 Swagger-API 的 GitHub 页面上阅读了该功能（还）根本不起作用。

如 here 和 [这里将是另一个链接，但我的声誉不够高，无法发布超过 2 个链接] 所述，自 2015 年 8 月以来已多次请求此功能，但没有太多运气。

现在this issue on the Swagger-API github，其中一位贡献者评论道：

这需要对模型进行重大重构，并且正在进行中。 2017 年 3 月 3 日

这导致了后来的评论：

将在 3.0.0 支持中得到支持，详情请参见 feature/3.0.0-rc2 分支。 2017 年 6 月 27 日

在2017 年 8 月 9 日，有人问什么时候发布 3.0.0 版，没有进一步的回应。

因此，总而言之，对数组/列表示例的支持已经在工作中，应该在 3.0.0 版本中可用，但没有更多关于何时发布的消息。

【讨论】：

令人印象深刻的分析，真的。
它不适用于 Springfox 3.0.0，我刚刚测试过。不生成 JSON 数组 [...]，而是生成字符串 "[...]"。

【解决方案3】：

您只需使用Reflection 表示法。使用

@ApiModelProperty(dataType = "[Ljava.lang.String;")

工作正常，但我不能举例子。

这是结果：

{
  "field": [
    "string"
  ]
}

【讨论】：

嗨丹尼尔，是的，它以所需格式生成输出，但问题是生成带有示例值的输出。
这适用于[Ljava.lang.String;，但不适用于[Ljava.time. LocalDateTime;。
哥们，你是个传奇人物！非常感谢:)
修复这个问题花了我 2 个小时，这是唯一有效的方法，谢谢！

【解决方案4】：

尝试如下初始化@ApiModelProperty：

public class MyClass {
    ....
    @ApiModelProperty(
        position = 2, datatype="List", example = "PRD1, PRD2, PRD3"
    )
    private List<String> productIdentifiers;
    ....
}

【讨论】：

我已经更新了原始问题中的详细信息。如果您需要更多详细信息，请告诉我
它不适用于 Springfox 3.0.0，我刚刚测试过。不生成 JSON 数组 [...]，而是生成字符串 "[...]"。

【解决方案5】：

Swagger API 似乎不支持这一点。同时你可以使用这个 Springfox Plugin 来生成一个单例列表示例（一个值列表）https://github.com/aaitmouloud/springfox-collection-example-plugin

只需将此添加给您pom.xml

<dependency>
    <groupId>com.github.aaitmouloud</groupId>
    <artifactId>springfox-collection-example-plugin</artifactId>
    <version>2.9.2</version>
</dependency>

并将正确的类导入您的 Spring 上下文

@ComponentScan({"springfox.collection.example.plugins"})

然后你应该在你的属性上声明一个单值示例，它会被插件转换为一个单例列表示例（适用于所有 java.util.Collection 类）

@ApiModelProperty(value ="my property description", example = "2019-12-20T12:00:00")
@NotNull
private List<LocalDateTime> dates;

免责声明：我是这个插件的作者。

【讨论】：

【解决方案6】：

这是一个对象列表的工作示例。招摇版本 2.9.2。只需要将 dataType 定义为“List”，它将在 swagger 文档中呈现。查找附件中渲染的ProductAll列表。

@ApiModel
public class ProductGetAllDTO {
    @ApiModelProperty(example="20")
    private String count;
    @ApiModelProperty(dataType="List", value = "rows")
    private List<ProductAll> rows;
}

【讨论】：

这不回答 OP。

【解决方案7】：

没有一个解决方案对我有用。正如this Baeldung article 中解释的那样，除了在数据模型中包含示例值@ApiModelProperty

@ApiModel
public class Foo {
    private long id;
    @ApiModelProperty(name = "name", dataType = "List", example = "[\"str1\", \"str2\", \"str3\"]")
    private List<String> name;

Controller 也必须用@ApiImplicitParams 注释，让 Swagger 指向数据模型：

@RequestMapping(method = RequestMethod.POST, value = "/foos")
@ResponseStatus(HttpStatus.CREATED)
@ResponseBody
@ApiImplicitParams({ @ApiImplicitParam(name = "foo", 
  value = "List of strings", paramType = "body", dataType = "Foo") })
public Foo create(@RequestBody final Foo foo) {

您可能会注意到dataType 指向类Foo。

【讨论】：

【解决方案8】：

我将示例更改为下面的代码并且它有效。

public class MyClass {
....
@ApiModelProperty(
    position = 2, datatype="List", example = "'[''{''PRD1''}','{''PRD2''}'']"
)
private List<String> productIdentifiers;
....
}

【讨论】：

它不适用于 Springfox 3.0.0，我刚刚测试过。不会生成 JSON 数组 [...]，而是生成包含所有撇号"'[...]'" 的原始字符串。

【解决方案9】：

在 V3 中，您可以省略 dataType 定义和示例值。 Swagger 将根据数据类型生成示例。列表将呈现为 [ { ... YourCustomObject-Properties ...}]

【讨论】：