Add :except as an option to Adapter::Attributes

This supports passing `except:`  as an option to `render` or as an
option to `has_many`, etc. declrations. This is useful when avoiding
circular includes.

The `except` name was chosen to mirror behavior found in the 0.8x
branch.

docs/general/adapters.md

@@ -180,6 +180,19 @@ It could be combined, like above, with other paths in any combination desired.
   render json: @posts, include: 'author.comments.**'
 ```
 
+#### Excluded
+
+Sometimes you want to omit a specific field or association during serialization.
+You can use the `except` option for this:
+
+```ruby
+  render json: @posts, include: '*', except: :author
+```
+
+This is particularly helpful if you are using the recursive include wildstar
+(`**`), as it can lead to infinite recursion when you have associations that
+can be traversed in a cycle.
+
 ##### Security Considerations
 
 Since the included options may come from the query params (i.e. user-controller):

docs/general/serializers.md

@@ -64,6 +64,7 @@ Where:
   - `unless:`
   - `virtual_value:`
   - `polymorphic:` defines if polymorphic relation type should be nested in serialized association.
+  - `except`: Specify attributes or associations to be ommitted from serialization
 - optional: `&block` is a context that returns the association's attributes.
   - prevents `association_name` method from being called.
   - return value of block is used as the association value.

lib/active_model/serializer/attributes.rb

@@ -14,10 +14,12 @@ module Attributes
 
         # Return the +attributes+ of +object+ as presented
         # by the serializer.
-        def attributes(requested_attrs = nil, reload = false)
+        def attributes(options = {}, reload = false)
+          requested_attrs = options[:only]
+          excepts = Array(options[:except])
           @attributes = nil if reload
           @attributes ||= self.class._attributes_data.each_with_object({}) do |(key, attr), hash|
-            next if attr.excluded?(self)
+            next if attr.excluded?(self) || excepts.include?(key)
             next unless requested_attrs.nil? || requested_attrs.include?(key)
             hash[key] = attr.value(self)
           end

lib/active_model_serializers/adapter/attributes.rb

@@ -33,7 +33,9 @@ def serializable_hash_for_single_resource(options)
 
       def resource_relationships(options)
         relationships = {}
+        excepts = Array(options[:except])
         serializer.associations(@include_tree).each do |association|
+          next if excepts.include?(association.key)
           relationships[association.key] ||= relationship_value_for(association, options)
         end
 
@@ -45,7 +47,8 @@ def relationship_value_for(association, options)
         return unless association.serializer && association.serializer.object
 
         opts = instance_options.merge(include: @include_tree[association.key])
-        relationship_value = Attributes.new(association.serializer, opts).serializable_hash(options)
+        hash_opts = options.merge(except: association.options[:except])
+        relationship_value = Attributes.new(association.serializer, opts).serializable_hash(hash_opts)
 
         if association.options[:polymorphic] && relationship_value
           polymorphic_type = association.serializer.object.class.name.underscore
@@ -63,12 +66,14 @@ def cache_attributes
       end
 
       def resource_object_for(options)
+        fields = options.fetch(:fields, {})
+        fields = fields.merge(except: options[:except]) if options[:except]
         if serializer.class.cache_enabled?
           @cached_attributes.fetch(serializer.cache_key(self)) do
-            serializer.cached_fields(options[:fields], self)
+            serializer.cached_fields(fields, self)
           end
         else
-          serializer.cached_fields(options[:fields], self)
+          serializer.cached_fields(fields, self)
         end
       end
     end

lib/active_model_serializers/adapter/json_api.rb

@@ -285,7 +285,7 @@ def process_relationship(serializer, include_tree)
       #     foo: 'bar'
       #   }
       def attributes_for(serializer, fields)
-        serializer.attributes(fields).except(:id)
+        serializer.attributes(only: fields, except: :id)
       end
 
       # {http://jsonapi.org/format/#document-resource-objects Document Resource Objects}

test/action_controller/serialization_test.rb

@@ -140,6 +140,17 @@ def render_fragment_changed_object_with_relationship
 
           render json: like
         end
+
+        def render_object_except
+          blog = Blog.new(id: 1, name: 'Blogariffic')
+          blog.articles = [
+            Post.new(id: 1, title: 'Hello', body: 'world'),
+            Post.new(id: 2, title: 'Moby Dick', body: 'Call me Ishmael.')
+          ]
+          blog.writer = Author.new(id: 1, name: 'Joao Moura.')
+
+          render json: blog, except: [:articles, :name]
+        end
       end
 
       tests ImplicitSerializationTestController
@@ -464,6 +475,14 @@ def test_render_event_is_emmited
       ensure
         ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
       end
+
+      def test_render_object_except
+        get :render_object_except
+        assert_equal(
+          { id: 1, writer: { id: 1, name: 'Joao Moura.' } }.to_json,
+          @response.body
+        )
+      end
     end
   end
 end

test/serializers/associations_test.rb

@@ -289,6 +289,47 @@ def test_illegal_conditional_associations
 
           assert_match(/:if should be a Symbol, String or Proc/, exception.message)
         end
+
+        def test_association_except
+          # `except` can take an array
+          comment_serializer = Class.new(ActiveModel::Serializer) do
+            attributes :id, :body
+            belongs_to :author, except: [:posts, :roles, :bio]
+            belongs_to :post
+          end
+
+          # `except` can take a symbol
+          post_serializer = Class.new(ActiveModel::Serializer) do
+            attributes :id, :title, :body
+            has_many :comments, except: :post, serializer: comment_serializer
+          end
+
+          # Circular dependency created:
+          # - post has_many comments
+          # - comment belongs_to post
+          # excluding the "post" association on comment resolves it when
+          # we are including nested associations
+
+          author = Author.new(id: 1, name: 'Alice')
+          post = Post.new(id: 7, title: 'Do work', body: 'work work work')
+          post.comments = [
+            Comment.new(post: post, author: author, id: 2, body: 'I agree'),
+            Comment.new(post: post, author: author, id: 3, body: 'Right')
+          ]
+
+          hash = serializable(post, serializer: post_serializer, include: '**').serializable_hash
+
+          expected = {
+            id: 7,
+            title: 'Do work',
+            body: 'work work work',
+            comments: [
+              { id: 2, body: 'I agree', author: { id: 1, name: 'Alice' } },
+              { id: 3, body: 'Right', author: { id: 1, name: 'Alice' } }
+            ]
+          }
+          assert_equal(expected, hash)
+        end
       end
     end
   end