Swagger-core: ArraySchema annotation on model accessors doesn't map to API spec properly

[NathanStrong-Tripwire]

I'm using swagger-core 2.0.0 with Jackson 2.9.4 and Jersey 2.26.

I'll start that I'm learning-by-doing, and so it's possible I'm doing it wrong. If that's the case, please point me in the right direction. But I think I've found a .. design limitation? The basic gist of this issue is that there's OAS features that I'm having no success in leveraging via annotations, and I think it's a limitation of the annotation implementation.

Consider a model object:

public class ExampleModel {
  private String[] stringArray;

  @ArraySchema(
    schema = @Schema(
        description = "Hello, World!",
        example = "Lorem ipsum dolor set"
    )
  )
  public void setStringArray(String[] value) { stringArray = value; }
  public String[] getStringArray() { return stringArray; }
}

The resulting openapi.json snippet ends up looking like:

"components": {
  "schemas": {
    "ExampleModel": {
      "type": "object",
      "properties": {
        "stringArray": {
          "type": "array",
          "description": "Hello, World!",
          "example":"Lorem ipsum dolor set"
          "items": {
            "type": "string",
            "description": "Hello, World!"
          }
        }
      }
    }
  }
}

There's two problems with this output:

1. Notice that the description field from the array element is also emitted for the array itself. This results in some ugly redundancy when processed by Swagger UI, and there's no way to specify the array's description separately from the element.
2. The example field is completely broken. The @Schema annotation doesn't support arrays for the example field, which clashes with the spec. Manually written JSON/YAML allows this (scroll down to the "Array Example" section).

If you try something like @Schema(example = "[ \"example 1\",\"example2\"]") you end up with a string representation of a JSON array, not an actual array. So, the long and short is that there's no (obvious) way to specify an array example via annotations.

My desired output would be something like:

"components": {
  "schemas": {
    "ExampleModel": {
      "type": "object",
      "properties": {
        "stringArray": {
          "type": "array",
          "description": "An array of lorem ipsum dolor set",
          "example": [ "Lorem", "ipsum", "dolor", "set" ],
          "items": {
            "type": "string",
            "description": "Hello, World!"
          }
        }
      }
    }
  }
}

I expect that would involve adding a "description" and a string[] example field to @ArraySchema, so the annotation that generated the above might look like:

@ArraySchema(
    description = "An array of lorem ipsum dolor set",
    example = {"Lorem", "ipsum", "dolor", "set"},
    schema = @Schema(
        description = "Hello, World!"
    )
)

[frantuma]

fixed in #2815, introducing new @ArraySchema field arraySchema; please check this test resource for an example matching your scenario.

[RAM237]

Meanwhile, this didn't add a description field to the @ArraySchema, so no ability to show fancy comment for the whole array (only for items inside array which doesn't look that nice as desired...).

[RAM237]

Meanwhile, this didn't add a description field to the @ArraySchema, so no ability to show fancy comment for the whole array (only for items inside array which doesn't look that nice as desired...).

I'm taking it back, I missed the point.
Specifying it as follows works like a charm, thanks!!

@ArraySchema(schema = @Schema(...),
        arraySchema = @Schema(description = "Your description for Array Schema here"))