Swagger List Not Mapping in Example Java

Question

I am using Swagger 3.0. I am not able to map List of objects in example request in swagger-ui. Attaching the screenshot for reference. Same is happening for other data types as well like Strings and Maps.

Request Structure -

"requestBody": {
  "description": "MyPartner Cards Request",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MyPartnerCardInfoRequest",
        "exampleSetFlag": false
      },
      "example": {
        "cards": [
          {
            "cardId": "HERO_LOYALTY_WELCOME_CARD",
            "templateId": "partner_welcome_card",
            "cardVariantId": "partner_welcome_card",
            "componentId": "basesheet"
          },
          {
            "cardId": "HERO_LOYALTY_BANNER_CARD",
            "templateId": "partner_welcome_card",
            "cardVariantId": "partner_welcome_card",
            "componentId": "basesheet"
          }
        ]
      },
      "exampleSetFlag": true
    }
  },
  "required": true
}

Was expecting to map the data type correctly.

Answer 1

Here's a valid sample of your exact description. It seems to work fine on swagger-ui. Although, you have an additional property in your payload which is throwing an error for exampleSetFlag. This is not a valid keyword in OpenAPI schema.

Your example seems to load fine, though

{
  "openapi" : "3.0.3",
  "info" : {
    "title" : "test",
    "version" : "1.0.0"
  },
  "servers" : [ ],
  "paths" : {
    "/endpoint" : {
      "post" : {
        "summary" : "stack",
        "parameters" : [ ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/MyPartnerCardInfoRequest",
                "exampleSetFlag": false
              },
              "example" : {
                "cards" : [ {
                  "cardId" : "HERO_LOYALTY_WELCOME_CARD",
                  "templateId" : "partner_welcome_card",
                  "cardVariantId" : "partner_welcome_card",
                  "componentId" : "basesheet"
                }, {
                  "cardId" : "HERO_LOYALTY_BANNER_CARD",
                  "templateId" : "partner_welcome_card",
                  "cardVariantId" : "partner_welcome_card",
                  "componentId" : "basesheet"
                } ]
              },
              "exampleSetFlag": true
            }
          },
          "required" : true
        },
        "responses" : {
          "201" : {
            "description" : "Created",
            "headers" : {
              "location" : {
                "schema" : {
                  "type" : "string"
                }
              }
            },
            "content" : {
              "application/json" : {
                "schema" : { }
              }
            }
          }
        }
      }
    }
  },
  "components" : {
    "schemas" : {
      "MyPartnerCardInfoRequest" : {
        "type" : "object",
        "properties" : {
          "cards" : {
            "type" : "array",
            "items" : { }
          }
        }
      }
    }
  }
}

The preferred keyword going forward with OpenAPI 3.x.x is the examples (plural) keyword which accepts a collection of schemas. This allows multiple examples of the same payload.

{
  "openapi": "3.0.3",
  "info": {
    "title": "test",
    "version": "1.0.0"
  },
  "servers": [],
  "paths": {
    "/endpoint": {
      "post": {
        "summary": "stack",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MyPartnerCardInfoRequest"
              },
              "examples": {
                "example_1": {
                  "value": {
                    "cards": [
                      {
                        "cardId": "HERO_LOYALTY_WELCOME_CARD",
                        "templateId": "partner_welcome_card",
                        "cardVariantId": "partner_welcome_card",
                        "componentId": "basesheet"
                      },
                      {
                        "cardId": "HERO_LOYALTY_BANNER_CARD",
                        "templateId": "partner_welcome_card",
                        "cardVariantId": "partner_welcome_card",
                        "componentId": "basesheet"
                      }
                    ]
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "location": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MyPartnerCardInfoRequest": {
        "type": "object",
        "properties": {
          "cards": {
            "type": "array",
            "items": {}
          }
        }
      }
    }
  }
}