Question

How to specify @Schema.examples where each element is an array? For example, you want to show possible combinations of a fixed-size collection.

Affected Version

2.2.40

Context

This is a valid OAS 3.1 schema showing two examples for the triple collection:
["one","two","three"] and ["four","five","six"]:

"ModelWithCollectionExamples": {
  "type": "object",
  "properties": {
    "triple": {
      "type": "array",
      "description": "Three words",
      "examples": [
        [
          "one",
          "two",
          "three"
        ],
        [
          "four",
          "five",
          "six"
        ]
      ],
      "items": {
        "type": "string"
      }
    }
  }
}

Swagger UI renders it correctly as an array of two elements where each element contains an array of three elements:

Additional Details

I tried to define the POJO model like this:

@Getter
@Setter
@AllArgsConstructor
public class ModelWithCollectionExamples {

  @Schema(
      description = "Three words",
      examples = {"[\"one\",\"two\", \"three\"]","[\"four\",\"five\", \"six\"]"})
  private List<String> triple;
}

Unfortunately, that renders examples as array of two escaped strings:

"ModelWithCollectionExamples": {
  "type": "object",
  "properties": {
    "triple": {
      "type": "array",
      "description": "Three words",
      "examples": [
        "[\"one\",\"two\", \"three\"]",
        "[\"four\",\"five\", \"six\"]"
      ],
      "items": {
        "type": "string"
      }
    }
  }
}

As a side note, I used the @Schema for the collection to overcome the issue 5012 otherwise the examples would not be generated at all. But that's a separate issue. If the issue is solved I would have used @ArraySchema(arraySchema=@Schema(examples = {...})) in the code snippet above.

Checklist

• I have searched the existing issues and documentation before asking.
• I have provided enough information for others to understand my question.