Minato Rails Serializer

A lightweight and high-performance JSON serialization layer for Rails, built on top of the Panko Serializer.

Minato::Rails::Serializer seamlessly integrates with Rails' render json:, offering automatic serializer detection, a simple DSL for root keys, and the flexibility to override behavior directly in the controller, all with a focus on convention over configuration.

Installation

Add this line to your application's Gemfile:

gem 'minato-rails-serializer'

And then execute:

$ bundle install

Usage

The gem is designed to be as intuitive as possible, integrating with the standard Rails workflow.

1. Creating a Serializer

Create your serializers by inheriting from the Minato::Rails::Serializer::Base base class.

# app/serializers/post_serializer.rb
class PostSerializer < Minato::Rails::Serializer::Base
  attributes :id, :title, :body
end

2. Basic Rendering in Controllers

Thanks to the included Railtie, the gem modifies render json: to automatically detect and use the corresponding serializer for your model.

In your controller, you can simply render the object:

class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])
    # The gem will automatically look for `PostSerializer`
    render json: @post
  end

  def index
    @posts = Post.all
    # It also works for collections
    render json: @posts
  end
end

3. Using the root DSL

You can define a default root key directly in your serializer, which will be used to wrap the JSON output.

# app/serializers/user_serializer.rb
class UserSerializer < Minato::Rails::Serializer::Base
  # Sets 'user' as the root for single objects and infers 'users' for collections
  root :user

  attributes :id, :name, :email
end

Now, when rendering:

# In a `show` action
render json: @user
# Output:
# {
#   "user": { "id": 1, "name": "...", "email": "..." }
# }

# In an `index` action
render json: @users
# Output:
# {
#   "users": [
#     { "id": 1, "name": "...", "email": "..." },
#     { "id": 2, "name": "...", "email": "..." }
#   ]
# }

You can also specify a custom plural name:

class ProductSerializer < Minato::Rails::Serializer::Base
  root :product, :products_list

  # ...
end

4. Overriding Options in the render Call

The gem offers full flexibility, allowing you to override the default behavior directly in the render call.

Overriding the Serializer Use the :serializer option to force the use of a different serializer than the inferred default.

# Assuming an AdminUserSerializer exists with more attributes
def show
  @user = User.find(params[:id])
  render json: @user, serializer: AdminUserSerializer
end

Overriding the Root Key (:root) Use the :root option to set a custom root key for a specific request, overriding the DSL.

def profile
  @user = current_user
  # The output will be wrapped in "profile", ignoring the `root :user` from the DSL.
  render json: @user, root: :profile
end

Disabling the Root Key To remove the root key (even if defined in the DSL), pass root: false.

def show
  @user = User.find(params[:id])
  # Returns the JSON object without any root key
  render json: @user, root: false
end

Development

This project uses Docker and Docker Compose to ensure a consistent development and testing environment.

Run the test suite:

$ docker compose run run minato-rails-serializer

The entrypoint script defined in compose.yml will automatically create, migrate, and prepare the test database for the dummy application before the RSpec suite is executed. Manual database setup is no longer required.

To open an interactive shell inside the container for debugging or running other commands (like rails c from the dummy app), use:

$ docker compose run minato-rails-serializer sh

License

The gem is available as open source under the terms of the MIT License.