active_model_serializers 0.10.7 → 0.10.14

data/docs/howto/add_relationship_links.md

@@ -1,140 +0,0 @@
-[Back to Guides](../README.md)
-
-# How to add relationship links
-
-ActiveModelSerializers offers you many ways to add links in your JSON, depending on your needs.
-The most common use case for links is supporting nested resources.
-
-The following examples are without included relationship data (`include` param is empty),
-specifically the following Rails controller was used for these examples:
-
-```ruby
-class Api::V1::UsersController < ApplicationController
-  def show
-    render jsonapi: User.find(params[:id]),
-      serializer: Api::V1::UserSerializer,
-      include: []
-  end
-end
-```
-
-Bear in mind though that ActiveModelSerializers are [framework-agnostic](outside_controller_use.md), Rails is just a common example here.
-
-### Links as an attribute of a resource
-**This is applicable to JSON and Attributes adapters**
-
-You can define an attribute in the resource, named `links`.
-
-```ruby
-class Api::V1::UserSerializer < ActiveModel::Serializer
-  include Rails.application.routes.url_helpers
-
-  attributes :id, :name
-
-  attribute :links do
-    id = object.id
-    {
-      self: api_v1_user_path(id),
-      microposts: api_v1_microposts_path(user_id: id)
-    }
-  end
-end
-```
-
-Using the `JSON` adapter, this will result in:
-
-```json
-{
-  "user": {
-    "id": "1",
-    "name": "John",
-    "links": {
-      "self": "/api/v1/users/1",
-      "microposts": "/api/v1/microposts?user_id=1"
-    }
-  }
-}
-```
-
-
-### Links as a property of the resource definiton
-**This is only applicable to JSONAPI adapter**
-
-You can use the `link` class method to define the links you need in the resource's primary data.
-
-```ruby
-class Api::V1::UserSerializer < ActiveModel::Serializer
-  attributes :id, :name
-
-  link(:self) { api_v1_user_path(object.id) }
-  link(:microposts) { api_v1_microposts_path(user_id: object.id) }
-end
-```
-
-Using the `JSONAPI` adapter, this will result in:
-
-```json
-{
-  "data": {
-    "id": "1",
-    "type": "users",
-    "attributes": {
-      "name": "Example User"
-    },
-    "links": {
-      "self": "/api/v1/users/1",
-      "microposts": "/api/v1/microposts?user_id=1"
-    }
-  }
-}
-```
-
-### Links that follow the JSONAPI spec
-**This is only applicable to JSONAPI adapter**
-
-If you have a JSONAPI-strict client that you are working with (like `ember-data`)
-you need to construct the links inside the relationships. Also the link to fetch the
-relationship data must be under the `related` attribute, whereas to manipulate the
-relationship (in case of many-to-many relationship) must be under the `self` attribute.
-
-You can find more info in the [spec](http://jsonapi.org/format/#document-resource-object-relationships).
-
-Here is how you can do this:
-
-```ruby
-class Api::V1::UserSerializer < ActiveModel::Serializer
-  attributes :id, :name
-
-  has_many :microposts, serializer: Api::V1::MicropostSerializer do
-    link(:related) { api_v1_microposts_path(user_id: object.id) }
-
-    microposts = object.microposts
-    # The following code is needed to avoid n+1 queries.
-    # Core devs are working to remove this necessity.
-    # See: https://github.com/rails-api/active_model_serializers/issues/1325
-    microposts.loaded? ? microposts : microposts.none
-  end
-end
-```
-
-This will result in:
-
-```json
-{
-  "data": {
-    "id": "1",
-    "type": "users",
-    "attributes": {
-      "name": "Example User"
-    },
-    "relationships": {
-      "microposts": {
-        "data": [],
-        "links": {
-          "related": "/api/v1/microposts?user_id=1"
-        }
-      }
-    }
-  }
-}
-```

data/docs/howto/add_root_key.md

@@ -1,62 +0,0 @@
-[Back to Guides](../README.md)
-
-# How to add root key
-
-Add the root key to your API is quite simple with ActiveModelSerializers. The **Adapter** is what determines the format of your JSON response. The default adapter is the ```Attributes``` which doesn't have the root key, so your response is something similar to:
-
-```json
-{
-  "id": 1,
-  "title": "Awesome Post Tile",
-  "content": "Post content"
-}
-```
-
-In order to add the root key you need to use the ```JSON``` Adapter, you can change this in an initializer:
-
-```ruby
-ActiveModelSerializers.config.adapter = :json
-```
-
-Note that adapter configuration has no effect on a serializer that is called
-directly, e.g. in a serializer unit test. Instead, something like
-`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.
-
-You can also specify a class as adapter, as long as it complies with the ActiveModelSerializers adapters interface.
-It will add the root key to all your serialized endpoints.
-
-ex:
-
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "Awesome Post Tile",
-    "content": "Post content"
-  }
-}
-```
-
-or if it returns a collection:
-
-```json
-{
-  "posts": [
-    {
-      "id": 1,
-      "title": "Awesome Post Tile",
-      "content": "Post content"
-    },
-    {
-      "id": 2,
-      "title": "Another Post Tile",
-      "content": "Another post content"
-    }
-  ]
-}
-```
-
-[There are several ways to specify root](../general/serializers.md#root) when using the JSON adapter.

data/docs/howto/grape_integration.md

@@ -1,42 +0,0 @@
-[Back to Guides](../README.md)
-
-The ActiveModelSerializers grape formatter relies on the existence of `env['grape.request']` which is implemeted by `Grape::Middleware::Globals`. You can meet his dependency by calling it before mounting the endpoints.
-
-In the simpliest way:
-
-```
-class API < Grape::API
-  # @note Make sure this is above you're first +mount+
-  use Grape::Middleware::Globals
-end
-```
-
-or more like what is shown in current Grape tutorials:
-
-```
-module MyApi
-  class ApiBase < Grape::API
-    use Grape::Middleware::Globals
-
-    require 'grape/active_model_serializers'
-    include Grape::ActiveModelSerializers
-
-    mount MyApi::V1::ApiBase
-  end
-end
-```
-
-You could meet this dependency with your own middleware. The invocation might look like:
-
-```
-module MyApi
-  class ApiBase < Grape::API
-    use My::Middleware::Thingamabob
-
-    require 'grape/active_model_serializers'
-    include Grape::ActiveModelSerializers
-
-    mount MyApi::V1::ApiBase
-  end
-end
-```

data/docs/howto/outside_controller_use.md

@@ -1,66 +0,0 @@
-[Back to Guides](../README.md)
-
-## Using ActiveModelSerializers Outside Of A Controller
-
-### Serializing a resource
-
-In ActiveModelSerializers versions 0.10 or later, serializing resources outside of the controller context is fairly simple:
-
-```ruby
-# Create our resource
-post = Post.create(title: "Sample post", body: "I love Active Model Serializers!")
-
-# Optional options parameters for both the serializer and instance
-options = {serializer: PostDetailedSerializer, username: 'sample user'}
-
-# Create a serializable resource instance
-serializable_resource = ActiveModelSerializers::SerializableResource.new(post, options)
-
-# Convert your resource into json
-model_json = serializable_resource.as_json
-```
-The object that is passed to `ActiveModelSerializers::SerializableResource.new` can be a single resource or a collection.
-The additional options are the same options that are passed [through controllers](../general/rendering.md#explicit-serializer).
-
-### Looking up the Serializer for a Resource
-
-If you want to retrieve the serializer class for a specific resource, you can do the following:
-
-```ruby
-# Create our resource
-post = Post.create(title: "Another Example", body: "So much fun.")
-
-# Optional options parameters
-options = {}
-
-# Retrieve the default serializer for posts
-serializer = ActiveModel::Serializer.serializer_for(post, options)
-```
-
-You could also retrieve the serializer via:
-
-```ruby
-ActiveModelSerializers::SerializableResource.new(post, options).serializer
-```
-
-Both approaches will return the serializer class that will be used for the resource.
-
-Additionally, you could retrieve the serializer instance for the resource via:
-
-```ruby
-ActiveModelSerializers::SerializableResource.new(post, options).serializer_instance
-```
-
-## Serializing before controller render
-
-At times, you might want to use a serializer without rendering it to the view. For those cases, you can create an instance of `ActiveModelSerializers::SerializableResource` with
-the resource you want to be serialized and call `.as_json`.
-
-```ruby
-def create
-  message = current_user.messages.create!(message_params)
-  message_json = ActiveModelSerializers::SerializableResource.new(message).as_json
-  MessageCreationWorker.perform(message_json)
-  head 204
-end
-```

data/docs/howto/passing_arbitrary_options.md

@@ -1,27 +0,0 @@
-[Back to Guides](../README.md)
-
-# Passing Arbitrary Options To A Serializer
-
-In addition to the [`serialization_scope`](../general/serializers.md#scope), any options passed to `render`
-that are not reserved for the [adapter](../general/rendering.md#adapter_opts)
-are available in the serializer as [instance_options](../general/serializers.md#instance_options).
-
-For example, we could pass in a field, such as `user_id` into our serializer.
-
-```ruby
-# posts_controller.rb
-class PostsController < ApplicationController
-  def dashboard
-    render json: @post, user_id: 12
-  end
-end
-
-# post_serializer.rb
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-
-  def comments_by_me
-    Comments.where(user_id: instance_options[:user_id], post_id: object.id)
-  end
-end
-```

data/docs/howto/serialize_poro.md

@@ -1,73 +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 in most situations:
-
-```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
-```
-
-The [ActiveModel::Serializer::Lint::Tests](../../lib/active_model/serializer/lint.rb)
-define and validate which methods ActiveModelSerializers expects to be implemented.
-
-An implementation of the complete spec is included either for use or as reference:
-[`ActiveModelSerializers::Model`](../../lib/active_model_serializers/model.rb).
-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`.
-
-*IMPORTANT*: There is a surprising behavior (bug) in the current implementation of ActiveModelSerializers::Model that
-prevents an accessor from modifying attributes on the instance.  The fix for this bug
-is a breaking change, so we have made an opt-in configuration.
-
-New applications should set:
-
-```ruby
-ActiveModelSerializers::Model.derive_attributes_from_names_and_fix_accessors
-```
-
-Existing applications can use the fix *and* avoid breaking changes
-by making a superclass for new models. For example:
-
-```ruby
-class SerializablePoro < ActiveModelSerializers::Model
-  derive_attributes_from_names_and_fix_accessors
-end
-```
-
-So that `MyModel` above would inherit from `SerializablePoro`.
-
-`derive_attributes_from_names_and_fix_accessors` prepends the `DeriveAttributesFromNamesAndFixAccessors`
-module and does the following:
-
-- `id` will *always* be in the attributes. (This is until we separate out the caching requirement for POROs.)
-- Overwrites the `attributes` method to that it only returns declared attributes.
- `attributes` will now be a frozen hash with indifferent access.
-
-For more information, see [README: What does a 'serializable resource' look like?](../../README.md#what-does-a-serializable-resource-look-like).

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"
-    }
-  }
-}
-```