swagger @ApiModelProperty example value for List 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 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

@Anil Bharadia what response did you get for `dataType=List"`? Also just to test precisely, what swagger version/dependency are you using? — Naman, Dec 19 '16 at 09:16
@nullpointer I am getting "PRD1, PRD2, PRD3" for all this my tries. — Anil Bharadia, Dec 19 '16 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 https://github.com/swagger-api/swagger-core/issues/1855 and https://github.com/swagger-api/swagger-core/issues/3863 — Honza Zidek, Jan 25 '21 at 12:40
@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. — Anil Bharadia, Jan 25 '21 at 16:19

score 25 · Answer 1 · edited Mar 19 '20 at 03:53

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

edited Mar 19 '20 at 03:53

Matt Byrne

4,908
3
35
52

answered May 02 '18 at 10:38

dane_griffiths

339
5
10

Unfortunately, the same doesn't work for a list/set of Integer or Long values – Teja Jan 31 '19 at 06:32
@MattByrne, yep, this works. Sweet! My original comment is no longer valid, so deleted it to avoid misleading anyone. – Lauri Harpf Mar 28 '20 at 11:12
Works with v3.0.0 of Springfox. – Srikanta Jan 20 '21 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 `"[...]"`. – Honza Zidek Jan 25 '21 at 12:35
Doesn't work (`provides "addLines": "[\"AddLine1\"]"` as it should). – Dims Apr 25 '22 at 10:12

score 17 · Answer 2 · answered Sep 19 '17 at 15:09

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.

It does not work with Springfox 3.0.0, I have just tested it. Does not produce a JSON array `[...]`, but a string `"[...]"`. — Honza Zidek, Jan 25 '21 at 12:35

score 9 · Answer 3 · answered May 24 '17 at 18:13

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

answered May 24 '17 at 18:13

Daniel Borges

329
3
5

Hi Daniel, yes it generates the output in desired format, but the question is to generate output with example values. – Anil Bharadia May 25 '17 at 07:25
This works with `[Ljava.lang.String;`, but not with `[Ljava.time. LocalDateTime;`. – jaco0646 Aug 10 '18 at 15:12
Man, you are a legendary! Thank you so much :) – Pavel Gordon Jul 30 '19 at 16:26
Fixing this took me 2 hours, and this is the only thing that worked, thank you! – Dmytro Kostyushko Jun 11 '21 at 12:50

score 2 · Answer 4 · edited Jul 11 '17 at 09:20

2

Try to initialize @ApiModelProperty as follows:

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

edited Jul 11 '17 at 09:20

John Moutafis

22,254
11
68
112

answered Dec 06 '16 at 06:40

Zeeshan Arif

467
4
14

I have updated details in the original question. Please let me know if you need more details – Anil Bharadia Feb 10 '17 at 06:16
It does not work with Springfox 3.0.0, I have just tested it. Does not produce a JSON array `[...]`, but a string `"[...]"`. – Honza Zidek Jan 25 '21 at 12:35

score 2 · Answer 5 · answered Jul 26 '19 at 22:33

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.

score 1 · Answer 6 · answered Jan 02 '20 at 20:53

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.

score 0 · Answer 7 · answered Jan 22 '19 at 17:22

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

answered Jan 22 '19 at 17:22

bpedroso

4,617
3
29
34

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`"'[...]'"`. – Honza Zidek Jan 25 '21 at 12:38

score 0 · Answer 8 · answered Jul 31 '19 at 03:01

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

This does not answer the OP. – Honza Zidek Jan 25 '21 at 12:37 — Honza Zidek, Jan 25 '21 at 12:37

score 0 · Answer 9 · answered Mar 30 '21 at 09:57

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

answered Mar 30 '21 at 09:57

MatthiasFranz

111
1
6

score 0 · Answer 10 · answered Feb 21 '23 at 07:27

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

swagger @ApiModelProperty example value for List property

10 Answers10

Linked

Related