Control How Required Types Appear in Doc

[timscott]

Using type validators displays required type in the docs in only terms of Ruby. This is wrong because the interface protocol is never in Ruby. It's HTTP, xml or json. In any case, when the documentation for a parameter shows "Hash" or "TrueClass, FalseClass" it's nonsensical to the consumer of the API who likely as not has zero knowledge of Ruby. There should be a way to show types more abstracted.

[saneshark]

:+1: I would also say that validators should be abstracted into a separate gem altogether. I like this gem for documentation, but have no desire to use it for validation of types as I leave that sort of handling to ActiveRecord and custom error handling.

[saneshark]

Furthermore, example JSON should possibly use something like JSON-Schema specs gem and a format for showing the examples where it could be shown that a particular attribute returned in the response could be null or not. An IOS API consumer for example might want to know what attributes of an object could be null, and that may not be gleaned directly from the example JSON.

[jeremywadsack]

I agree about putting validators in a separate gem. We also don't need that overhead.