Add support to top-level links objects

it's a generic object which can be used to declare
a top-level links object as specified on jsonapi

http://jsonapi.org/format/#document-top-level

Author: leandrocp

README.md

@@ -138,6 +138,14 @@ render json: @post, meta: { total: 10 }, meta_key: "custom_meta"
 
 `meta` will only be included in your response if you are using an Adapter that supports `root`, as JsonAPI and Json adapters, the default adapter (FlattenJson) doesn't have `root`.
 
+### Links
+
+A top-level `links` object may be specified in the `render` call:
+
+```ruby
+render json: @post, links: { self: "/posts/1" }
+```
+
 ### Overriding association methods
 
 If you want to override any association, you can use:

lib/active_model/serializer.rb

@@ -150,14 +150,15 @@ def self.root_name
       name.demodulize.underscore.sub(/_serializer$/, '') if name
     end
 
-    attr_accessor :object, :root, :meta, :meta_key, :scope
+    attr_accessor :object, :root, :meta, :meta_key, :links, :scope
 
     def initialize(object, options = {})
       @object     = object
       @options    = options
       @root       = options[:root]
       @meta       = options[:meta]
       @meta_key   = options[:meta_key]
+      @links      = options[:links]
       @scope      = options[:scope]
 
       scope_name = options[:scope_name]

lib/active_model/serializer/adapter.rb

@@ -22,7 +22,10 @@ def serializable_hash(options = nil)
 
       def as_json(options = nil)
         hash = serializable_hash(options)
-        include_meta(hash) unless self.class == FlattenJson
+        unless self.class == FlattenJson
+          include_meta(hash)
+          include_links(hash)
+        end
         hash
       end
 
@@ -86,6 +89,10 @@ def meta_key
         serializer.meta_key || "meta"
       end
 
+      def links
+        serializer.links if serializer.respond_to?(:links)
+      end
+
       def root
         serializer.json_key.to_sym if serializer.json_key
       end
@@ -94,6 +101,11 @@ def include_meta(json)
         json[meta_key] = meta if meta
         json
       end
+
+      def include_links(json)
+        json["links"] = links if links
+        json
+      end
     end
   end
 end

lib/active_model/serializer/array_serializer.rb

@@ -5,7 +5,7 @@ class ArraySerializer
       include Enumerable
       delegate :each, to: :@objects
 
-      attr_reader :root, :meta, :meta_key
+      attr_reader :root, :meta, :meta_key, :links
 
       def initialize(objects, options = {})
         @root = options[:root]
@@ -24,6 +24,7 @@ def initialize(objects, options = {})
         end
         @meta     = options[:meta]
         @meta_key = options[:meta_key]
+        @links    = options[:links]
       end
 
       def json_key

test/action_controller/serialization_test.rb

@@ -57,6 +57,17 @@ def render_array_using_implicit_serializer_and_meta
           end
         end
 
+        def render_array_using_implicit_serializer_and_links
+          with_adapter ActiveModel::Serializer::Adapter::JsonApi do
+
+            @profiles = [
+              Profile.new({ name: 'Name 1', description: 'Description 1', comments: 'Comments 1' })
+            ]
+
+            render json: @profiles, links: { self: "/profiles/1" }
+          end
+        end
+
         def render_object_with_cache_enabled
           @comment = Comment.new({ id: 1, body: 'ZOMG A COMMENT' })
           @author  = Author.new(id: 1, name: 'Joao Moura.')
@@ -268,6 +279,29 @@ def test_render_array_using_implicit_serializer_and_meta
         assert_equal expected.to_json, @response.body
       end
 
+      def test_render_array_using_implicit_serializer_and_links
+        get :render_array_using_implicit_serializer_and_links
+
+        expected = {
+          data: [
+            {
+              id: assigns(:profiles).first.id.to_s,
+              type: "profiles",
+              attributes: {
+                name: "Name 1",
+                description: "Description 1"
+              }
+            }
+          ],
+          links: {
+            self: "/profiles/1"
+          }
+        }
+
+        assert_equal 'application/json', @response.content_type
+        assert_equal expected.to_json, @response.body
+      end
+
       def test_render_with_cache_enable
         expected = {
           id: 1,

test/array_serializer_test.rb

@@ -45,6 +45,12 @@ def test_meta_and_meta_key_attr_readers
         assert_equal @serializer.meta_key, "the meta key"
       end
 
+      def test_links_attr_reader
+        @serializer = ArraySerializer.new([@comment, @post], links: {"self": "/array/1"})
+
+        assert_equal @serializer.links, {"self": "/array/1"}
+      end
+
       def test_root_default
         @serializer = ArraySerializer.new([@comment, @post])
         assert_equal @serializer.root, nil

test/serializers/links_test.rb

@@ -0,0 +1,95 @@
+require 'test_helper'
+
+module ActiveModel
+  class Serializer
+    class LinksTest < Minitest::Test
+      def setup
+        ActionController::Base.cache_store.clear
+        @blog = Blog.new(id: 1,
+                         name: 'AMS Hints',
+                         writer: Author.new(id: 2, name: "Steve"),
+                         articles: [Post.new(id: 3, title: "AMS")])
+      end
+
+      def test_links_is_present_with_root
+        serializer = AlternateBlogSerializer.new(@blog, links: {"self": "/blogs/1"})
+        adapter = ActiveModel::Serializer::Adapter::Json.new(serializer)
+        expected = {
+          blog: {
+            id: 1,
+            title: "AMS Hints"
+          },
+          "links" => {
+            self: "/blogs/1"
+          }
+        }
+        assert_equal expected, adapter.as_json
+      end
+
+      def test_links_is_not_included_when_root_is_missing
+        # load_adapter uses FlattenJson Adapter
+        adapter = load_adapter(links: {"self": "/blogs/1"})
+        expected = {
+          id: 1,
+          title: "AMS Hints"
+        }
+        assert_equal expected, adapter.as_json
+      end
+
+      def test_links_is_not_present_on_arrays_without_root
+        serializer = ArraySerializer.new([@blog], links: {"self": "/blogs/1"})
+        # FlattenJSON doesn't have support to root
+        adapter = ActiveModel::Serializer::Adapter::FlattenJson.new(serializer)
+        expected = [{
+          id: 1,
+          name: "AMS Hints",
+          writer: {
+            id: 2,
+            name: "Steve"
+          },
+          articles: [{
+            id: 3,
+            title: "AMS",
+            body: nil
+          }]
+        }]
+        assert_equal expected, adapter.as_json
+      end
+
+      def test_links_is_present_on_arrays_with_root
+        serializer = ArraySerializer.new([@blog], links: {"self": "/blogs/1"})
+        # JSON adapter adds root by default
+        adapter = ActiveModel::Serializer::Adapter::Json.new(serializer)
+        expected = {
+          blogs: [{
+            id: 1,
+            name: "AMS Hints",
+            writer: {
+              id: 2,
+              name: "Steve"
+            },
+            articles: [{
+              id: 3,
+              title: "AMS",
+              body: nil
+            }]
+          }],
+          "links" => {
+            self: "/blogs/1"
+          }
+        }
+        assert_equal expected, adapter.as_json
+      end
+
+      private
+
+      def load_adapter(options)
+        adapter_opts, serializer_opts =
+          options.partition { |k, _| ActionController::Serialization::ADAPTER_OPTION_KEYS.include? k }.map { |h| Hash[h] }
+
+        serializer = AlternateBlogSerializer.new(@blog, serializer_opts)
+        ActiveModel::Serializer::Adapter::FlattenJson.new(serializer, adapter_opts)
+      end
+    end
+  end
+end