swagger @ApiModelProperty example value for List<String> property

Question

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

Pengelly

@Anil Bharadia what response did you get for dataType=List<String>"? Also just to test precisely, what swagger version/dependency are you using? – Brie

@nullpointer I am getting "PRD1, PRD2, PRD3" for all this my tries. – Pengelly

@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 – Gilkey

@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. – Pengelly

Answer 1

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"
    ],

Packston

Unfortunately, the same doesn't work for a list/set of Integer or Long values – Thetos

@MattByrne, yep, this works. Sweet! My original comment is no longer valid, so deleted it to avoid misleading anyone. – Selfassertion

Works with v3.0.0 of Springfox. – Adulthood

It does not work with Springfox 3.0.0, I have just tested it. Does not produce a JSON array [...], but a string "[...]". – Gilkey

Doesn't work (provides "addLines": "[\"AddLine1\"]" as it should). – Basketry

Answer 2

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.

Cancellate

Impressive analysis, really. – Castor

It does not work with Springfox 3.0.0, I have just tested it. Does not produce a JSON array [...], but a string "[...]". – Gilkey

Answer 3

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"
  ]
}

Cullin

Hi Daniel, yes it generates the output in desired format, but the question is to generate output with example values. – Pengelly

This works with [Ljava.lang.String;, but not with [Ljava.time. LocalDateTime;. – Holography

Man, you are a legendary! Thank you so much :) – Headman

Fixing this took me 2 hours, and this is the only thing that worked, thank you! – Tolmach

Answer 4

Try to initialize @ApiModelProperty as follows:

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

Glance

I have updated details in the original question. Please let me know if you need more details – Pengelly

It does not work with Springfox 3.0.0, I have just tested it. Does not produce a JSON array [...], but a string "[...]". – Gilkey

Answer 5

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.

Bussy

Answer 6

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.

Fawn

Answer 7

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

Iodometry

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"'[...]'". – Gilkey

Answer 8

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 list rendered in the attached picture.

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

Booze

This does not answer the OP. – Gilkey

Answer 9

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 ...}]

Wringer

Answer 10

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"
  ],

Worriment