fix: enable swagger generator to add referenced schema for an array of hashes param

[ftsanjuan]

Context
Currently, the swagger generator produces a schema that uses {type: "string"} for any param that is specified as an Array, even when the param is actually an Array of Hashes.

Example:
Currently, the following annotation for a param...

param :products, Array, of: Hash, required: true, desc: "Products list" do
  param :id, String, desc: "product id", required: true
  param :name, String, desc: "product name", required: true
end

would get rendered in a schema as:

{
  "name": "products",
  "type": "array",
  "items": {
    "type": "string"
  },
  "in": "formData",
  "required": true,
  "description": "Products list"
}

(note that the nested parameters for the Array are completely missing in the rendered schema)

Solution
The following fix looks into the param_desc to verify whether the param is a Hash, and if so, attempts to generate a referenced schema for its parameters.

The name of the reference is derived in a similar fashion to the naming for an operation id using the swagger_op_id_for_path as seen here, but the name is suffixed with _param_[name of the param]

[dmitry-solomadin]

Hey @iNecas any chance someone can review that, we are using a fork with @ftsanjuan's changes

[sebfie]

I also need it, can someone review it? He worked for this project, I think he deserves a review.

[byjus-taha-abbas]

@mathieujobin Please review and merge this one, thanks!

[mathieujobin]

I don't know... There are multiple PRs that attempt at fixing the swagger output.

Gotta be careful i think

And this PR had conflicts.

Needs to be rebased

[ftsanjuan]

Thank you @mathieujobin 🙏🏼