Add warnings about global adapter config to docs

[mrpinsky]

Purpose

Clarify effects of global adapter configuration in relation on serializer behavior

Changes

Add warnings to docs

Caveats

No code changes, just documentation

Additional helpful information

This came up for me when trying to test serializer behavior. I wanted to the serialization to include a root key, but despite setting ActiveModelSerializers.config.adapter = :json in an initializer, my calls to serializer.as_json didn't have the root key. When I tried to repro in a fresh Rails app, I found that calls to render in a controller did add a root key, but direct calls to serializer.as_json and serializer.serializable_hash with no arguments did not. Digging in, I think the problem is in ActiveModel::Serializer:112-115:

    # @api private
    def self.serialization_adapter_instance
      @serialization_adapter_instance ||= ActiveModelSerializers::Adapter::Attributes
    end

that is, @serialization_adapter_instance is never set, and so it defaults to the hard-coded Attributes adapter if it isn't passed in to serializable_hash (which it isn't if you just use as_json);

    # @return [Hash] containing the attributes and first level
    # associations, similar to how ActiveModel::Serializers::JSON is used
    # in ActiveRecord::Base.
    def serializable_hash(adapter_options = nil, options = {}, adapter_instance = self.class.serialization_adapter_instance)
      adapter_options ||= {}
      options[:include_directive] ||= ActiveModel::Serializer.include_directive_from_options(adapter_options)
      resource = attributes_hash(adapter_options, options, adapter_instance)
      relationships = associations_hash(adapter_options, options, adapter_instance)
      resource.merge(relationships)
    end
    alias to_hash serializable_hash
    alias to_h serializable_hash

    # @see #serializable_hash
    def as_json(adapter_opts = nil)
      serializable_hash(adapter_opts)
    end

[bf4]

This is a good point. I'd like to clarify the intention a bit, that serializers on their own should always just serialize the attributes and possibly associations as if it were the Attributes adapter.

I quickly wrote up some words for example of what I'm thinking.

[bf4]

Good point. Maybe:

> **IMPORTANT**: Adapter configuration has *no effect* on a serializer instance being used directly.
> That is, `UserSerializer.new(user).as_json` will *always* behave as if the adapter were the 'Attributes' adapter.
> See [Outside Controller Usage](../howto/outside_controller_use.md) for more details on recommended usage.

[mrpinsky]

@bf4 I've changed the language in both places to better reflect your intentions, but I'm curious as to why it's supposed to behave this way. It seems like it makes the behavior of the system less consistent, meaning that you'd need to write different tests for the serializer behavior in a serializer test vs a controller test. How do you envision testing the serializers?

[bf4]

Looks good. want to add yourself to the changelog?

[mrpinsky]

Changelog updated