Guides > Rendering

Rendering

Implicit (Default) Serializer

ActiveModelSerializers automatically integrates with your Rails app. , when you use render :json in your controllers, Rails will now first search for a serializer for the object and use it if available.

class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])

    render json: @post
  end
end

Here Rails will look for a serializer named PostSerializer, and if it exists, use it to serialize the @post.

Namespaced Models

When serializing a model inside a namespace (e.g. Api::V1::Post), ActiveModelSerializers will expect the corresponding serializer to be inside the same namespace (namely Api::V1::PostSerializer).

Model Associations and Nested Serializers

When declaring a serializer for a model with associations, such as:

class PostSerializer < ActiveModel::Serializer
  has_many :comments
end

ActiveModelSerializers will look for PostSerializer::CommentSerializer in priority, and fall back to ::CommentSerializer if the former does not exist. This allows for more control over the way a model gets serialized as an association of an other model.

For example, in the following situation:

class CommentSerializer < ActiveModel::Serializer
  attributes :body, :date, :nb_likes
end

class PostSerializer < ActiveModel::Serializer
  has_many :comments
  class CommentSerializer < ActiveModel::Serializer
    attributes :body_short
  end
end

ActiveModelSerializers will use PostSerializer::CommentSerializer (thus including only the :body_short attribute) when serializing a Comment as part of a Post, but use ::CommentSerializer when serializing a Comment directly (thus including :body, :date, :nb_likes).

Route Helpers

If you wish to use Rails url helpers for link generation, e.g., link(:resources) { resources_url }, ensure your application sets Rails.application.routes.default_url_options.

Rails.application.routes.default_url_options = {
    host: 'example.com'
}

Explicit Serializer

If you wish to use a serializer other than the default, you can explicitly pass it to the renderer.

1. For a resource:

  render json: @post, serializer: PostPreviewSerializer

2. For a resource collection:

Specify the serializer for each resource with each_serializer

render json: @posts, each_serializer: PostPreviewSerializer

The default serializer for collections is CollectionSerializer.

Specify the collection serializer with the serializer option.

render json: @posts, serializer: CollectionSerializer, each_serializer: PostPreviewSerializer

SerializableResource Options

The options hash passed to render or ActiveModelSerializers::SerializableResource.new(resource, options) are partitioned into:

Adapter Options

Serializer Options

Arbitrary Options

In Rails, the options are also passed to the as_json(options) or to_json(options) methods on the resource serialization by Rails JSON renderer. Therefore they are important to know about, but not part of ActiveModelSerializers.

See Architecture for more information.

Pagination

Usage Outside of a Controller (Without render)