Nested Exposure attributes are flatten in documents

[calfzhou]

the Nested Exposure generates incorrect documentation, all nested fields are flatten

expose :name
expose :contact_info do
  expose :phone
  expose :email
end

it should generate (document)

name: ...
contact_info:
  phone: ...
  email: ...

but now it generates

name: ...
phone: ...
email: ...

[calfzhou]

module API::Entities
      class Contact < Grape::Entity
        expose :name, documentation: { type: String }
        expose :contact_info do
          expose :phone, documentation: { type: String }
          expose :email, documentation: { type: String }
        end
      end
end

in rails c, API::Entities::Contact.documentation will now generate:

{
  "name": {
    "type": "String"
  },
  "phone": {
    "type": "String"
  },
  "email": {
    "type": "String"
  }
}

[calfzhou]

just read source code, seems not very easy to fix. now i have to move nested exposures to another entity to make document right

module API::Entities
  class ContactInfo < Grape::Entity
    expose :phone, documentation: { type: String }
    expose :email, documentation: { type: String }
  end

  class Contact < Grape::Entity
    expose :name, documentation: { type: String }
    expose :object, as: :contact_info, using: API::Entities::ContactInfo,
                    documentation: { type: 'API::ContactInfo' }
  end
end

[cantidio]

+1

[pinifloyd]

+1

[marshall-lee]

The problem :documentation is a hash with arbitrary keys like { desc: '...', type: 'some_type', foo: 123, bar: 456 }. So current structure of documentation doesn't allow to preserve nesting. We can add a :nested key here so documentation would be like this:

{
  name: { type: String },
  contact_info: {
    nested: {
      phone: { type: String },
      email: { type: String }
    }
  }
}

But we cannot introduce this :nested key now since documentation doesn't restrict keys anyhow. What if someone uses :nested keyword in documentation?

#151 fixes this flattening issue but now documentation doesn't emit documentation for nested exposures at all. I think it's better than this flattening after all.

Maybe it's worth to introduce a Documentation object that responds to #[] method returning documentation values for keys(:desc, :type, etc) and also has a method nested giving access to documentation of nested exposures. But here we should think about possible caveats.

[marshall-lee]

I also think that for now nested exposures with :documentation should raise an exception. It's temporary until we decide what to do with nesting.