CODEWITHSUNDEEP
javaswaggerspringfox
Anil Bharadia
Anil Bharadia

Reputation: 2820

swagger @ApiModelProperty example value for List<String> property

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

Upvotes: 51

Views: 105376

Answers (10)

vuhoanghiep1993
vuhoanghiep1993

Reputation: 871

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

Upvotes: 0

MatthiasFranz
MatthiasFranz

Reputation: 111

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

Upvotes: 0

dane_griffiths
dane_griffiths

Reputation: 369

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

Upvotes: 28

Carlos Cavero
Carlos Cavero

Reputation: 3176

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.

Upvotes: 1

tksilicon
tksilicon

Reputation: 4426

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

Upvotes: 0

clapsus
clapsus

Reputation: 462

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.

Upvotes: 2

bpedroso
bpedroso

Reputation: 4897

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

Upvotes: 0

KoenC
KoenC

Reputation: 316

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.

Upvotes: 17

Zeeshan Arif
Zeeshan Arif

Reputation: 499

Try to initialize @ApiModelProperty as follows:

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

Upvotes: 2

Daniel Borges
Daniel Borges

Reputation: 329

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

Upvotes: 9

Related Questions