Injected responses are not having proper schema reference

[nandorholozsnyak]

Is your feature request related to a problem? Please describe.
When the examples are being injected to the OpenAPI documentation these items are not having a proper schema setup and it can lead to problems to the reader not having the full schema only the example that might not represent the full schema.

Describe the solution you'd like
Some way that the different examples could be associated with a schema.

Additional context

Response code with 201 is having a schema ref, but the others are not.

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenAPI definition",
    "version": "v0"
  },
  "servers": [
    {
      "url": "http://localhost:8080",
      "description": "Generated server url"
    }
  ],
  "paths": {
    "/users": {
      "post": {
        "tags": [
          "user-rest-controller"
        ],
        "operationId": "postUser",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserResponse"
                },
                "examples": {
                  "When user creation is successful": {
                    "description": "",
                    "$ref": "#/components/examples/response_postUser_application_json_When user creation is successful"
                  }
                }
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "When authorization header is empty": {
                    "description": "",
                    "$ref": "#/components/examples/response_postUser_application_json_When authorization header is empty"
                  }
                }
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "When authorization header is containing a non-admin user": {
                    "description": "",
                    "$ref": "#/components/examples/response_postUser_application_json_When authorization header is containing a non-admin user"
                  }
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "When shop card does not exist": {
                    "description": "",
                    "$ref": "#/components/examples/response_postUser_application_json_When shop card does not exist"
                  }
                }
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "When email address is taken": {
                    "description": "",
                    "$ref": "#/components/examples/response_postUser_application_json_When email address is taken"
                  },
                  "When passwords do not match": {
                    "description": "",
                    "$ref": "#/components/examples/response_postUser_application_json_When passwords do not match"
                  }
                }
              }
            }
          },
          "450": {
            "content": {
              "application/json": {
                "examples": {
                  "When region is invalid": {
                    "description": "",
                    "$ref": "#/components/examples/response_postUser_application_json_When region is invalid"
                  }
                }
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "When unknown exception happens": {
                    "description": "",
                    "$ref": "#/components/examples/response_postUser_application_json_When unknown exception happens"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UserModel": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "shopCardId": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "enum": [
              "EU",
              "US"
            ]
          }
        }
      },
      "UserResponse": {
        "type": "object",
        "properties": {
          "user": {
            "$ref": "#/components/schemas/UserModel"
          }
        }
      }
    },
    "examples": {
      "response_postUser_application_json_When unknown exception happens": {
        "description": "",
        "value": "{\n  \"path\" : \"/users\",\n  \"errors\" : [ {\n    \"code\" : \"UNKNOWN_ERROR\",\n    \"message\" : \"Unknown exception\"\n  } ]\n}"
      },
      "request_postUser_application_json_User creation fails because two password do not match": {
        "description": "",
        "value": "{\n  \"user\" : {\n    \"email\" : \"already-taken@email.com\",\n    \"password\" : \"password\",\n    \"passwordConfirmation\" : \"anotherPassword\",\n    \"shopCardId\" : \"ABC123\",\n    \"region\" : \"EU\"\n  }\n}"
      },
      "response_postUser_application_json_When passwords do not match": {
        "description": "",
        "value": "{\n  \"path\" : \"/users\",\n  \"errors\" : [ {\n    \"code\" : \"PASSWORD_DOES_NOT_MATCH\",\n    \"message\" : \"Passwords do not match\"\n  } ]\n}"
      },
      "request_postUser_application_json_User creation fails because the shop card does not exist": {
        "description": "",
        "value": "{\n  \"user\" : {\n    \"email\" : \"already-taken@email.com\",\n    \"password\" : \"password\",\n    \"passwordConfirmation\" : \"password\",\n    \"shopCardId\" : \"UNKNOWN-CARD\",\n    \"region\" : \"EU\"\n  }\n}"
      },
      "response_postUser_application_json_When user creation is successful": {
        "description": "",
        "value": "{\n  \"user\" : {\n    \"id\" : \"USER-ID\",\n    \"email\" : \"test@email.com\",\n    \"shopCardId\" : \"ABC123\",\n    \"region\" : \"EU\"\n  }\n}"
      },
      "response_postUser_application_json_When region is invalid": {
        "description": "",
        "value": "{\n  \"path\" : \"/users\",\n  \"errors\" : [ {\n    \"code\" : \"INVALID_REGION\",\n    \"message\" : \"Region is invalid:[US]\"\n  } ]\n}"
      },
      "response_postUser_application_json_When shop card does not exist": {
        "description": "",
        "value": "{\n  \"path\" : \"/users\",\n  \"errors\" : [ {\n    \"code\" : \"UNKNOWN_SHOPPING_CART\",\n    \"message\" : \"Shop card with id:[UNKNOWN-CARD] is unknown\"\n  } ]\n}"
      },
      "response_postUser_application_json_When authorization header is empty": {
        "description": "",
        "value": "{\n  \"path\" : \"/users\",\n  \"errors\" : [ {\n    \"code\" : \"UNAUTHORIZED\",\n    \"message\" : \"Unauthorized access\"\n  } ]\n}"
      },
      "response_postUser_application_json_When authorization header is containing a non-admin user": {
        "description": "",
        "value": "{\n  \"path\" : \"/users\",\n  \"errors\" : [ {\n    \"code\" : \"FORBIDDEN\",\n    \"message\" : \"Forbidden access\"\n  } ]\n}"
      },
      "request_postUser_application_json_User creation fails because the e-mail address is already registered": {
        "description": "",
        "value": "{\n  \"user\" : {\n    \"email\" : \"already-taken@email.com\",\n    \"password\" : \"password\",\n    \"passwordConfirmation\" : \"password\",\n    \"shopCardId\" : \"ABC123\",\n    \"region\" : \"EU\"\n  }\n}"
      },
      "response_postUser_application_json_When email address is taken": {
        "description": "",
        "value": "{\n  \"path\" : \"/users\",\n  \"errors\" : [ {\n    \"code\" : \"USER_ALREADY_EXIST\",\n    \"message\" : \"User already exists with e-mail:[already-taken@email.com]\"\n  } ]\n}"
      },
      "request_postUser_application_json_User creation is successful": {
        "description": "",
        "value": "{\n  \"user\" : {\n    \"email\" : \"test@email.com\",\n    \"password\" : \"password\",\n    \"passwordConfirmation\" : \"password\",\n    \"shopCardId\" : \"ABC123\",\n    \"region\" : \"EU\"\n  }\n}"
      }
    }
  }
}