At first glance this change may seem too big. But every move here is reasonable.
For instance It's impossible to solve #56 without removing nested_exposures. Removing nested_exposures requires different way to represent nesting trees so I cannot find something better than extract exposure logic from Entity at all.

But some problem is introduced with changing exposures from hash table to an array so grape-swagger will not work with this patch. And it's even unclear how to generate documentation now. Imagine this case:

expose :x, using: E1, if: :condition1
expose :x, using: E2, if: :condition2

Which one should the swagger pick: E1 or E2 ?

I can help with implementing a workaround for swagger but for now I don't know exactly how to fix it.

Maybe bring back construction of exposures as a hash table and deprecate it?
Or maybe fix grape-swagger and bump version requirement for grape-entity?

I'd like to merge this, it needs a detailed CHANGELOG entry and we have to discuss what to do about swagger. The conflicting cases should just have some predictable behavior.

I just read through swagger specification and didn't find anything that might help gracefully solve this issue.

But:

1. It tries to analyze only those exposures that has a :documentation option.
2. It fetches exposure_options by name (which now is not unique) to get its :using option only if there is no :type field in :documentation of exposure.
3. Grape::Entity.documentation (which is used by grape-swagger) still has an old rewriting nature. But I think that in this case it's good. Ones who use conditional exposures with different using values are forced to specify one :type for exposures with the same key (:as value or attribute name). This :type value could be simply 'object' or some 'AbstractEntity'.
4. According to previous point for any keygrape-swagger should pick :type from documentation or :using (if there's no :type) from the last exposure with this key and it's already implemented in documentation.
5. Grape::Entity.documentation still has an issue described in Nested Exposure attributes are flatten in documents #112. I propose to solve it traversing only root_exposures, not exposures.
6. Remove flat array of exposures. There's no need in this now.

I'd like to propose a workaround to grape-swagger based on a fact that new entities do not respond to exposures method. It would also require adding different versions of grape-entity to grape-swagger's travis matrix.

Any complains?

No complaints. Grape-swagger needs a lot of work too and as long as we offer people a path forward I'm cool with it. Please at the very least open issues with grape-swagger for anything introduced here.

@marshall-lee Lets get this merged? Amend CHANGELOG? We also probably need an UPGRADING document.

@dblock I'm working on CHANGELOG right now.
I'd like to write UPGRADING.md too. To what version we're upgrading? 0.5.0? Maybe change lib/grape_entity/version.rb in this patch too?

And what format should I use in UPGRADING?

0.5.0 makes sense

Oops, JRuby build failed. https://travis-ci.org/intridea/grape-entity/builds/72464413

Latest changes revealed some misbehavior in JRuby, I reported it here: jruby/jruby#3178

LOL, Now Rubocop suggests me in https://travis-ci.org/intridea/grape-entity/jobs/72467983:

Pass &:nesting? as an argument to take_while instead of a block.

But take_while with &:method is buggy in JRuby as I mentioned above.

But it's okay on jruby-head, lol.

@dblock I'm almost ready. Maybe you release 0.4.6 without these changes? Or just put all pending changes to 0.5.0?

@marshall-lee You've done some great work here. I emailed you about becoming a maintainer on grape-entity. Your first order of duty could be to release 0.4.6?

👍

great stuff, too bad it breaks https://github.com/Gild/ruby-swagger too. How does the UPGRADE look like? next time pls deprecate the method first..

I think the line @calfzhou is referring to is: https://github.com/ruby-grape/grape-swagger/blob/03ee40d41d71063236c4b0b1d468f69978ab308e/lib/grape-swagger/doc_methods.rb#L261

ok this did the trick for me, super hacky, dirty and for sure not complete...

class BaseDecorator < Grape::Entity
    def self.exposures
      extract_exposures(root_exposures, {})
    end

    private

    def self.extract_exposures(root, hash, prefix = nil)
      root.each do |entity|
        key = "#{prefix}#{entity.attribute}"
        nested = prefix.nil? ? {} : { nested: true }
        if entity.is_a?(Grape::Entity::Exposure::NestingExposure)
          hash[key.to_sym] = {}
          extract_exposures(entity.nested_exposures, hash, key + '__')
        else
          hash[key.to_sym] = entity.send(:options).merge(nested)
        end
      end
      hash
    end
  end

@rngtng Want to give fixing ruby-grape/grape-swagger#314 a try?

@dblock I'd love to, if I find the time...let me see..