Question

我有一个类，其中有一个属性为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

Answer 1

TLDR：Swagger-API的贡献者之一已经开发了这个功能，可以在3.0.0版本中添加它，但是它还不确定何时发布。目前它位于Swagger-API GitHub上的feature / 3.0.0-rc2分支

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

如上所述here和 [这里将是另一个链接，但我的声誉不足以发布2个以上的链接] 自2015年8月以来已多次请求此功能运气不好。

现在this issue on the Swagger-API github，其中一位撰稿人评论道：

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

导致后来的评论：

支持3.0.0支持，详情请见功能/ 3.0.0-rc2分支。 2017年6月27日

在 2017年8月9日有人询问3.0.0版本的发布时间是否会有进一步的回复。

总而言之，对数组/列表的示例的支持已经开始工作，并且应该在3.0.0版本中提供，但没有关于何时发布的消息。

Answer 2

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

在ApiModelProperty中，将数据类型定义为List，并按如下所示编写示例：

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

以下是我的例子：

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

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

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

Answer 3

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

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

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

结果如下：

{
  "field": [
    "string"
  ]
}

Answer 4

尝试按如下方式初始化@ApiModelProperty：

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

Answer 5

一个丑陋的解决方法，直到我们正确支持此功能，这为仅包含一个元素的列表生成示例，但至少允许显示比"string"更有用的内容是使用allowableValues：< / p>

@ApiModelProperty(position = 2, allowableValues = "PRD1")
// This generates -> "productIdentifiers": ["PRD1"]

Answer 6

这是对象列表的有效示例。 Swagger版本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;
}

Answer 7

我将示例更改为以下代码，并且可以正常工作。

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

Answer 8

Swagger API似乎不支持此功能。同时，您可以使用此Springfox插件生成单例列表示例（一个值列表）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;

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

Answer 9

没有一个解决方案对我有用。正如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。

Answer 10

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

swagger @ApiModelProperty List <string>属性的示例值

10 个答案: