agi_active_model_serializers 0.10.7

data/docs/howto/serialize_poro.md

@@ -0,0 +1,32 @@
+[Back to Guides](../README.md)
+
+# How to serialize a Plain-Old Ruby Object (PORO)
+
+When you are first getting started with ActiveModelSerializers, it may seem only `ActiveRecord::Base` objects can be serializable, but pretty much any object can be serializable with ActiveModelSerializers.  Here is an example of a PORO that is serializable:
+```ruby
+# my_model.rb
+class MyModel
+  alias :read_attribute_for_serialization :send
+  attr_accessor :id, :name, :level
+  
+  def initialize(attributes)
+    @id = attributes[:id]
+    @name = attributes[:name]
+    @level = attributes[:level]
+  end
+
+  def self.model_name
+    @_model_name ||= ActiveModel::Name.new(self)
+  end
+end
+```
+
+Fortunately, ActiveModelSerializers provides a [`ActiveModelSerializers::Model`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/model.rb) which you can use in production code that will make your PORO a lot cleaner.  The above code now becomes:
+```ruby
+# my_model.rb
+class MyModel < ActiveModelSerializers::Model
+  attributes :id, :name, :level
+end
+```
+
+The default serializer would be `MyModelSerializer`.

data/docs/howto/test.md

@@ -0,0 +1,154 @@
+[Back to Guides](../README.md)
+
+# How to test
+
+## Controller Serializer Usage
+
+ActiveModelSerializers provides a `assert_serializer` method to be used on your controller tests to
+assert that a specific serializer was used.
+
+```ruby
+class PostsControllerTest < ActionController::TestCase
+  test "should render post serializer" do
+    get :index
+    assert_serializer "PostSerializer"
+  end
+end
+```
+
+See [ActiveModelSerializers::Test::Serializer](../../lib/active_model_serializers/test/serializer.rb)
+for more examples and documentation.
+
+## Serialization against a schema
+
+### Dependencies
+
+To use the `assert_response_schema` you need to have the
+[`json_schema`](https://github.com/brandur/json_schema) on your Gemfile. Please
+add it to your Gemfile and run `$ bundle install`.
+
+### Minitest test helpers
+
+ActiveModelSerializers provides a `assert_response_schema` method to be used on your controller tests to
+assert the response against a [JSON Schema](http://json-schema.org/). Let's take
+a look in an example.
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+
+    render json: @post
+  end
+end
+```
+
+To test the `posts#show` response of this controller we need to create a file
+named `test/support/schemas/posts/show.json`. The helper uses a naming convention
+to locate the file.
+
+This file is a JSON Schema representation of our response.
+
+```json
+{
+  "properties": {
+    "title" : { "type" : "string" },
+    "content" : { "type" : "string" }
+  }
+}
+```
+
+With all in place we can go to our test and use the helper.
+
+```ruby
+class PostsControllerTest < ActionController::TestCase
+  test "should render right response" do
+    get :index
+    assert_response_schema
+  end
+end
+```
+
+#### Load a custom schema
+
+If we need to use another schema, for example when we have a namespaced API that
+shows the same response, we can pass the path of the schema.
+
+```ruby
+module V1
+  class PostsController < ApplicationController
+    def show
+      @post = Post.find(params[:id])
+
+      render json: @post
+    end
+  end
+end
+```
+
+```ruby
+class V1::PostsControllerTest < ActionController::TestCase
+  test "should render right response" do
+    get :index
+    assert_response_schema('posts/show.json')
+  end
+end
+```
+
+#### Change the schema path
+
+By default all schemas are created at `test/support/schemas`. If we are using
+RSpec for example we can change this to `spec/support/schemas` defining the
+default schema path in an initializer.
+
+```ruby
+ActiveModelSerializers.config.schema_path = 'spec/support/schemas'
+```
+
+#### Using with the Heroku’s JSON Schema-based tools
+
+To use the test helper with the [prmd](https://github.com/interagent/prmd) and
+[committee](https://github.com/interagent/committee).
+
+We need to change the schema path to the recommended by prmd:
+
+```ruby
+ActiveModelSerializers.config.schema_path = 'docs/schema/schemata'
+```
+
+We also need to structure our schemata according to Heroku's conventions
+(e.g. including
+[required metadata](https://github.com/interagent/prmd/blob/master/docs/schemata.md#meta-data)
+and [links](https://github.com/interagent/prmd/blob/master/docs/schemata.md#links).
+
+#### JSON Pointers
+
+If we plan to use [JSON
+Pointers](http://spacetelescope.github.io/understanding-json-schema/UnderstandingJSONSchema.pdf) we need to define the `id` attribute on the schema. Example:
+
+```js
+// attributes.json
+
+{
+  "id": "file://attributes.json#",
+  "properties": {
+    "name" : { "type" : "string" },
+    "description" : { "type" : "string" }
+  }
+}
+```
+
+```js
+// show.json
+
+{
+  "properties": {
+    "name": {
+      "$ref": "file://attributes.json#/properties/name"
+    },
+    "description": {
+      "$ref": "file://attributes.json#/properties/description"
+    }
+  }
+}
+```

data/docs/howto/upgrade_from_0_8_to_0_10.md

@@ -0,0 +1,265 @@
+[Back to Guides](../README.md)
+
+# How to migrate from `0.8` to `0.10` safely
+
+## Disclaimer
+### Proceed at your own risk
+This document attempts to outline steps to upgrade your app based on the collective experience of
+developers who have done this already. It may not cover all edge cases and situations that may cause issues,
+so please proceed with a certain level of caution.
+
+## Overview
+This document outlines the steps needed to migrate from `0.8` to `0.10`. The method described
+below has been created via the collective knowledge of contributions of those who have done
+the migration successfully. The method has been tested specifically for migrating from `0.8.3`
+to `0.10.2`.
+
+The high level approach is to upgrade to `0.10` and change all serializers to use
+a backwards-compatible `ActiveModel::V08::Serializer`or `ActiveModel::V08::CollectionSerializer`
+and a `ActiveModelSerializers::Adapter::V08Adapter`. After a few more manual changes, you should have the same
+functionality as you had with `AMS 0.8`. Then, you can continue to develop in your app by creating
+new serializers that don't use these backwards compatible versions and slowly migrate
+existing serializers to the `0.10` versions as needed.
+
+### `0.10` breaking changes
+- Passing a serializer to `render json:` is no longer supported
+
+```ruby
+render json: CustomerSerializer.new(customer) # rendered in 0.8, errors in 0.10
+```
+
+- Passing a nil resource to serializer now fails
+
+```ruby
+CustomerSerializer.new(nil) # returned nil in 0.8, throws error in 0.10
+```
+
+- Attribute methods are no longer defined on the serializer, and must be explicitly
+  accessed through `object`
+
+```ruby
+class MySerializer
+  attributes :foo, :bar
+
+  def foo
+    bar + 1 # bar does not work, needs to be object.bar in 0.10
+  end
+end
+```
+
+ - `root` option to collection serializer behaves differently
+
+```ruby
+# in 0.8
+ActiveModel::ArraySerializer.new(resources, root: "resources")
+# resulted in { "resources": <serialized_resources> }, does not work in 0.10
+```
+
+- No default serializer when serializer doesn't exist
+- `@options` changed to `instance_options`
+- Nested relationships are no longer walked by default. Use the `:include` option at **controller `render`** level to specify what relationships to walk. E.g. `render json: @post, include: {comments: :author}` if you want the `author` relationship walked, otherwise the json would only include the post with comments. See: https://github.com/rails-api/active_model_serializers/pull/1127
+- To emulate `0.8`'s walking of arbitrarily deep relationships use: `include: '**'`. E.g. `render json: @post, include: '**'`
+
+## Steps to migrate
+
+### 1. Upgrade the `active_model_serializer` gem in you `Gemfile`
+Change to `gem 'active_model_serializers', '~> 0.10'` and run `bundle install`
+
+### 2. Add `ActiveModel::V08::Serializer`
+
+```ruby
+module ActiveModel
+  module V08
+    class Serializer < ActiveModel::Serializer
+      include Rails.application.routes.url_helpers
+
+      # AMS 0.8 would delegate method calls from within the serializer to the
+      # object.
+      def method_missing(*args)
+        method = args.first
+        read_attribute_for_serialization(method)
+      end
+
+      alias_method :options, :instance_options
+
+      # Since attributes could be read from the `object` via `method_missing`,
+      # the `try` method did not behave as before. This patches `try` with the
+      # original implementation plus the addition of
+      # ` || object.respond_to?(a.first, true)` to check if the object responded to
+      # the given method.
+      def try(*a, &b)
+        if a.empty? || respond_to?(a.first, true) || object.respond_to?(a.first, true)
+          try!(*a, &b)
+        end
+      end
+
+      # AMS 0.8 would return nil if the serializer was initialized with a nil
+      # resource.
+      def serializable_hash(adapter_options = nil,
+                            options = {},
+                            adapter_instance =
+                              self.class.serialization_adapter_instance)
+        object.nil? ? nil : super
+      end
+    end
+  end
+end
+
+```
+Add this class to your app however you see fit. This is the class that your existing serializers
+that inherit from `ActiveMode::Serializer` should inherit from.
+
+### 3. Add `ActiveModel::V08::CollectionSerializer`
+```ruby
+module ActiveModel
+  module V08
+    class CollectionSerializer < ActiveModel::Serializer::CollectionSerializer
+      # In AMS 0.8, passing an ArraySerializer instance with a `root` option
+      # properly nested the serialized resources within the given root.
+      # Ex.
+      #
+      # class MyController < ActionController::Base
+      #   def index
+      #     render json: ActiveModel::Serializer::ArraySerializer
+      #       .new(resources, root: "resources")
+      #   end
+      # end
+      #
+      # Produced
+      #
+      # {
+      #   "resources": [
+      #     <serialized_resource>,
+      #     ...
+      #   ]
+      # }
+      def as_json(options = {})
+        if root
+          {
+            root => super
+          }
+        else
+          super
+        end
+      end
+
+      # AMS 0.8 used `DefaultSerializer` if it couldn't find a serializer for
+      # the given resource. When not using an adapter, this is not true in
+      # `0.10`
+      def serializer_from_resource(resource, serializer_context_class, options)
+        serializer_class =
+          options.fetch(:serializer) { serializer_context_class.serializer_for(resource) }
+
+        if serializer_class.nil? # rubocop:disable Style/GuardClause
+          DefaultSerializer.new(resource, options)
+        else
+          serializer_class.new(resource, options.except(:serializer))
+        end
+      end
+
+      class DefaultSerializer
+        attr_reader :object, :options
+
+        def initialize(object, options={})
+          @object, @options = object, options
+        end
+
+        def serializable_hash
+          @object.as_json(@options)
+        end
+      end
+    end
+  end
+end
+```
+Add this class to your app however you see fit. This is the class that existing uses of
+`ActiveModel::ArraySerializer` should be changed to use.
+
+### 4. Add `ActiveModelSerializers::Adapter::V08Adapter`
+```ruby
+module ActiveModelSerializers
+  module Adapter
+    class V08Adapter < ActiveModelSerializers::Adapter::Base
+      def serializable_hash(options = nil)
+        options ||= {}
+
+        if serializer.respond_to?(:each)
+          if serializer.root
+            delegate_to_json_adapter(options)
+          else
+            serializable_hash_for_collection(options)
+          end
+        else
+          serializable_hash_for_single_resource(options)
+        end
+      end
+
+      def serializable_hash_for_collection(options)
+        serializer.map do |s|
+          V08Adapter.new(s, instance_options)
+            .serializable_hash(options)
+        end
+      end
+
+      def serializable_hash_for_single_resource(options)
+        if serializer.object.is_a?(ActiveModel::Serializer)
+          # It is recommended that you add some logging here to indicate
+          # places that should get converted to eventually allow for this
+          # adapter to get removed.
+          @serializer = serializer.object
+        end
+
+        if serializer.root
+          delegate_to_json_adapter(options)
+        else
+          options = serialization_options(options)
+          serializer.serializable_hash(instance_options, options, self)
+        end
+      end
+
+      def delegate_to_json_adapter(options)
+        ActiveModelSerializers::Adapter::Json
+          .new(serializer, instance_options)
+          .serializable_hash(options)
+      end
+    end
+  end
+end
+```
+Add this class to your app however you see fit.
+
+Add
+```ruby
+ActiveModelSerializers.config.adapter =
+  ActiveModelSerializers::Adapter::V08Adapter
+```
+to `config/active_model_serializer.rb` to configure AMS to use this
+class as the default adapter.
+
+### 5. Change inheritors of `ActiveModel::Serializer` to inherit from `ActiveModel::V08::Serializer`
+Simple find/replace
+
+### 6. Remove `private` keyword from serializers
+Simple find/replace. This is required to allow the `ActiveModel::V08::Serializer`
+to have proper access to the methods defined in the serializer.
+
+You may be able to change the `private` to `protected`, but this is hasn't been tested yet.
+
+### 7. Remove references to `ActiveRecord::Base#active_model_serializer`
+This method is no longer supported in `0.10`.
+
+`0.10` does a good job of discovering serializers for `ActiveRecord` objects.
+
+### 8. Rename `ActiveModel::ArraySerializer` to `ActiveModel::V08::CollectionSerializer`
+Find/replace uses of `ActiveModel::ArraySerializer` with `ActiveModel::V08::CollectionSerializer`.
+
+Also, be sure to change the `each_serializer` keyword to `serializer` when calling making the replacement.
+
+### 9. Replace uses of `@options` to `instance_options` in serializers
+Simple find/replace
+
+## Conclusion
+After you've done the steps above, you should test your app to ensure that everything is still working properly.
+
+If you run into issues, please contribute back to this document so others can benefit from your knowledge.
+