swagger @ApiModelProperty example value for List property

Question

I have one class in which there is one property which is List

public class MyClass {
    ....
    @ApiModelProperty(position = 2)
         


        

Answer 1

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.

Answer 2

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

Answer 3

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.