active_model_serializers 0.10.3 → 0.10.12

data/docs/howto/serialize_poro.md

@@ -1,32 +0,0 @@
-[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
-  attr_accessor :id, :name, :level
-end
-```
-
-The default serializer would be `MyModelSerializer`.

data/docs/howto/test.md

@@ -1,154 +0,0 @@
-[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

@@ -1,265 +0,0 @@
-[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.
-