50

I have one class in which there is one property which is List<String>

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

This code generates the example values as following:

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

The example values here shown are not valid. My expected example values should be like :

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

I have tried passing example attribute as following but it is not generating proper value:

@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

Is there any way I can generate proper example value for List property ?

Update :

I have tried the solutions suggested by @nullpointer and @Zeeshan Arif

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

Update 2 :

Tried following approach which did not generate proper response

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

my maven dependency for swagger jar is :

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

Update github ticket for this issue

4
  • @Anil Bharadia what response did you get for dataType=List<String>"? Also just to test precisely, what swagger version/dependency are you using?
    – Naman
    Dec 19, 2016 at 9:16
  • @nullpointer I am getting "PRD1, PRD2, PRD3" for all this my tries. Dec 19, 2016 at 10:47
  • @AnilBharadia Have you solved it? I am struggling with the same problem, now in Springfox 3.0.0, and none of the provided answers does not work for me. See also github.com/swagger-api/swagger-core/issues/1855 and github.com/swagger-api/swagger-core/issues/3863 Jan 25, 2021 at 12:40
  • 1
    @HonzaZidek It has been so long I have worked on that project. As far as I remember, I was not able to solve this issue. I've tried some of the answers, not tried the answers provided recently. I'll try to create a sample project to test if new answers are working. Jan 25, 2021 at 16:19

10 Answers 10

25

I managed to get this to work, generating a List of Strings.

Within the ApiModelProperty with springfox 2, write your example as follows:

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

Here is my example:

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

When I render the swagger page, I get the following output:

"addLines": [
      "AddLine1",
      "AddLine2",
      "AddLine3",
      "AddLine4"
    ],
5
  • Unfortunately, the same doesn't work for a list/set of Integer or Long values
    – Teja
    Jan 31, 2019 at 6:32
  • @MattByrne, yep, this works. Sweet! My original comment is no longer valid, so deleted it to avoid misleading anyone. Mar 28, 2020 at 11:12
  • Works with v3.0.0 of Springfox.
    – Srikanta
    Jan 20, 2021 at 16:48
  • It does not work with Springfox 3.0.0, I have just tested it. Does not produce a JSON array [...], but a string "[...]". Jan 25, 2021 at 12:35
  • Doesn't work (provides "addLines": "[\"AddLine1\"]" as it should).
    – Dims
    Apr 25, 2022 at 10:12
17

TLDR: One of the contributers on Swagger-API has worked on this functionality to add this in version 3.0.0 but it's not sure yet when this will be released. For now it stands on the feature/3.0.0-rc2 branch at the Swagger-API GitHub

I've been working with Swagger for almost two months now and as our project progressed issues like this showed up. Now I did some research and read on the GitHub pages for the Swagger-API that this feature simply doesn't work (yet).

As described here and [here would be an other link but my reputation is not high enough to post more than 2 links] this feature has been requested several times since August 2015 with not much luck.

Now on this issue on the Swagger-API github, one of the contributors commented:

This takes a major refactoring of the models, which is on the way. 3 March 2017

which lead to a later comment:

Will be supported in 3.0.0 support, please see the feature/3.0.0-rc2 branch for details. 27 June 2017

And on 9 August 2017 someone asked when the release of version 3.0.0 would be with no further response.

So in conclusion, support for examples for arrays/Lists has been worked on and should be available in version 3.0.0 but no more news on when that would be released.

2
  • Impressive analysis, really.
    – Gangnus
    Sep 26, 2017 at 9:52
  • It does not work with Springfox 3.0.0, I have just tested it. Does not produce a JSON array [...], but a string "[...]". Jan 25, 2021 at 12:35
9

You just use Reflection notation. Using

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

works fine, but I can't put examples.

This is the result:

{
  "field": [
    "string"
  ]
}
4
  • Hi Daniel, yes it generates the output in desired format, but the question is to generate output with example values. May 25, 2017 at 7:25
  • This works with [Ljava.lang.String;, but not with [Ljava.time. LocalDateTime;.
    – jaco0646
    Aug 10, 2018 at 15:12
  • Man, you are a legendary! Thank you so much :) Jul 30, 2019 at 16:26
  • Fixing this took me 2 hours, and this is the only thing that worked, thank you! Jun 11, 2021 at 12:50
2

Try to initialize @ApiModelProperty as follows:

public class MyClass {
    ....
    @ApiModelProperty(
        position = 2, datatype="List", example = "PRD1, PRD2, PRD3"
    )
    private List<String> productIdentifiers;
    ....
}
2
  • I have updated details in the original question. Please let me know if you need more details Feb 10, 2017 at 6:16
  • It does not work with Springfox 3.0.0, I have just tested it. Does not produce a JSON array [...], but a string "[...]". Jan 25, 2021 at 12:35
2

This seems to not be supported by the Swagger API. In the mean time you can use this Springfox Plugin to generate a singleton list example (one value list) https://github.com/aaitmouloud/springfox-collection-example-plugin

Just add this to you pom.xml

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

And import the right classes to your Spring context

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

You should then declares a single value example on your property and it will be transformed to a singleton list example by the plugin (works for all java.util.Collection classes)

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

Disclaimer: I am the author of this plugin.

1

None of the solutions worked for me. As it is explained in this Baeldung article besides to include the Example Value in the data model with @ApiModelProperty

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

The Controller must also be annotated with @ApiImplicitParams to let Swagger point to the data model:

@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) {

You may notice that the dataType point to the class Foo.

0

I changed my example to the code below and it worked.

public class MyClass {
....
@ApiModelProperty(
    position = 2, datatype="List", example = "'[''{''PRD1''}','{''PRD2''}'']"
)
private List<String> productIdentifiers;
....
}
1
  • It does not work with Springfox 3.0.0, I have just tested it. Does not produce a JSON array [...], but exactly the original string including all the apostrophes"'[...]'". Jan 25, 2021 at 12:38
0

Here is a working example for list of objects. Swagger version 2.9.2. All that is needed is for the dataType to define as "List" and it will render in the swagger documentation. Find attached the ProductAll listenter image description here rendered in the attached picture.

@ApiModel
public class ProductGetAllDTO {
    @ApiModelProperty(example="20")
    private String count;
    @ApiModelProperty(dataType="List", value = "rows")
    private List<ProductAll> rows;
}
1
  • This does not answer the OP. Jan 25, 2021 at 12:37
0

In V3 you can just leave out dataType definition and example values. Swagger will generate examples based on data type. List will render as [ { ... YourCustomObject-Properties ...}]

0

I add @JsonProperty (com.fasterxml.jackson.annotation.JsonProperty) and it work:

@ApiModelProperty(value = "ID upload", example = "[\"AB11\",\"AC22\"]")
@JsonProperty("DOC_ID")
private ArrayList<String> DOC_ID;

In swagger:

  "DOC_ID": [
    "AB11",
    "AC22"
  ],

Not the answer you're looking for? Browse other questions tagged or ask your own question.