Added documentation support to parameters

[johnallen3d]

Additional documentation can be added to a parameter by providing a documentation hash.

params do
  optional :first_name, type: String, documentation: { example: 'Jim' }
  requires :last_name, type: String, documentation: { example: 'Smith' }
end

Previous discussion in this issue.

[dblock]

I like it, merging.

[mscrivo]

I know this is a very old PR, but it's important to note that examples on parameters are only supported in OpenAPI v3, which grape does not support. If you add an example on a param using this, and then run the resulting spec through any OpenAPI validator tool, it will fail. IMO, grape should only allow valid OpenAPI v2 documentation, until it supports v3 properly.

[dblock]

@mscrivo Want to add something in the README wrt OpenAPI versions?

[mscrivo]

@mscrivo Want to add something in the README wrt OpenAPI versions?

What would we say though? I'd prefer if people didn't hit this kind of thing in the first place and have to look in the README for some explanation. I'm thinking we need something that validates any documentation grape spits out against an OpenAPI v2 validator as a PR check, if that's at all possible.

Or someone puts in the effort to get the v3 migration done 😆

[dblock]

I'd prefer someone contribute to v4 migration too! But it could just say something like "Note: Grape currently supports OpenAPI x.y. See #xyz for adding v3 support."