Document new reflection options; support :foreign_key

docs/general/serializers.md

@@ -64,6 +64,9 @@ Where:
   - `unless:`
   - `virtual_value:`
   - `polymorphic:` defines if polymorphic relation type should be nested in serialized association.
+  - `type:` the resource type as used by JSON:API, especially on a `belongs_to` relationship.
+  - `class_name:` used to determine `type` when `type` not given
+  - `foreign_key:` used by JSON:API on a `belongs_to` relationship to avoid unnecessarily loading the association object.
 - 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/reflection.rb

@@ -9,6 +9,7 @@ module ActiveModel
     # @example
     #   class PostSerializer < ActiveModel::Serializer
     #     has_one :author, serializer: AuthorSerializer
+    #     belongs_to :boss, type: :users, foreign_key: :boss_id
     #     has_many :comments
     #     has_many :comments, key: :last_comments do
     #       object.comments.last(1)
@@ -58,12 +59,13 @@ module ActiveModel
           class_name = options.fetch(:class_name, name.to_s.camelize.singularize)
           class_name.underscore.pluralize.to_sym
         end
-        @foreign_key =
+        @foreign_key = options.fetch(:foreign_key) do
           if collection?
             "#{name.to_s.singularize}_ids".to_sym
           else
             "#{name}_id".to_sym
           end
+        end
       end
 
       # @api public