From 26bcdbe44adbf404a82f8be55b89002e8955c89f Mon Sep 17 00:00:00 2001 From: Benjamin Fleischer Date: Wed, 17 Aug 2016 16:16:13 -0500 Subject: [PATCH] Clean up docs --- docs/howto/add_root_key.md | 2 + docs/howto/grape_integration.md | 12 +++--- docs/howto/passing_arbitrary_options.md | 4 +- docs/howto/test.md | 2 + docs/howto/upgrade_from_0_8_to_0_10.md | 54 ++++++++++++------------- 5 files changed, 40 insertions(+), 34 deletions(-) diff --git a/docs/howto/add_root_key.md b/docs/howto/add_root_key.md index 3ee032e7..c27f47f6 100644 --- a/docs/howto/add_root_key.md +++ b/docs/howto/add_root_key.md @@ -1,3 +1,5 @@ +[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: diff --git a/docs/howto/grape_integration.md b/docs/howto/grape_integration.md index a5cd3675..9ff1353e 100644 --- a/docs/howto/grape_integration.md +++ b/docs/howto/grape_integration.md @@ -1,4 +1,6 @@ -The AMS 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. +[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: @@ -15,10 +17,10 @@ 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 @@ -30,10 +32,10 @@ You could meet this dependency with your own middleware. The invocation might lo module MyApi class ApiBase < Grape::API use My::Middleware::Thingamabob - + require 'grape/active_model_serializers' include Grape::ActiveModelSerializers - + mount MyApi::V1::ApiBase end end diff --git a/docs/howto/passing_arbitrary_options.md b/docs/howto/passing_arbitrary_options.md index e7fd8409..4e0fc9a0 100644 --- a/docs/howto/passing_arbitrary_options.md +++ b/docs/howto/passing_arbitrary_options.md @@ -11,7 +11,7 @@ For example, we could pass in a field, such as `user_id` into our serializer. ```ruby # posts_controller.rb class PostsController < ApplicationController - def dashboard + def dashboard render json: @post, user_id: 12 end end @@ -20,7 +20,7 @@ end class PostSerializer < ActiveModel::Serializer attributes :id, :title, :body - def comments_by_me + def comments_by_me Comments.where(user_id: instance_options[:user_id], post_id: object.id) end end diff --git a/docs/howto/test.md b/docs/howto/test.md index 6423f8d0..c66e0e9a 100644 --- a/docs/howto/test.md +++ b/docs/howto/test.md @@ -1,3 +1,5 @@ +[Back to Guides](../README.md) + # How to test ## Controller Serializer Usage diff --git a/docs/howto/upgrade_from_0_8_to_0_10.md b/docs/howto/upgrade_from_0_8_to_0_10.md index 2530e239..ed1eb453 100644 --- a/docs/howto/upgrade_from_0_8_to_0_10.md +++ b/docs/howto/upgrade_from_0_8_to_0_10.md @@ -5,8 +5,8 @@ ## 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. +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 @@ -14,8 +14,8 @@ below has been created via the collective knowledge of contributions of those wh 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` +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 @@ -23,38 +23,38 @@ 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": }, does not work in 0.10 ``` - + - No default serializer when serializer doesn't exist - `@options` changed to `instance_options` @@ -70,16 +70,16 @@ 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 @@ -90,7 +90,7 @@ module ActiveModel 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, @@ -104,7 +104,7 @@ module ActiveModel end ``` -Add this class to your app however you see fit. This is the class that your existing serializers +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` @@ -145,7 +145,7 @@ module ActiveModel # 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 = + serializer_class = options.fetch(:serializer) { serializer_context_class.serializer_for(resource) } if serializer_class.nil? # rubocop:disable Style/GuardClause @@ -170,7 +170,7 @@ module ActiveModel end end ``` -Add this class to your app however you see fit. This is the class that existing uses of +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` @@ -231,20 +231,20 @@ Add ActiveModelSerializers.config.adapter = ActiveModelSerializers::Adapter::V08Adapter ``` -to `config/active_model_serializer.rb` to configure AMS to use this +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. +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`. +This method is no longer supported in `0.10`. `0.10` does a good job of discovering serializers for `ActiveRecord` objects. @@ -260,4 +260,4 @@ Simple find/replace 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. - +