active_model_serializers 0.10.0 → 0.10.6

data/active_model_serializers.gemspec

@@ -19,33 +19,36 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   spec.executables   = []
 
-  spec.required_ruby_version = '>= 2.0.0'
+  spec.required_ruby_version = '>= 2.1'
 
-  rails_versions = '>= 4.0'
+  rails_versions = ['>= 4.1', '< 6']
   spec.add_runtime_dependency 'activemodel', rails_versions
-    # 'activesupport', rails_versions
-    # 'builder'
+  # 'activesupport', rails_versions
+  # 'builder'
 
   spec.add_runtime_dependency 'actionpack', rails_versions
-    # 'activesupport', rails_versions
-    # 'rack'
-    # 'rack-test', '~> 0.6.2'
+  # 'activesupport', rails_versions
+  # 'rack'
+  # 'rack-test', '~> 0.6.2'
 
-  spec.add_runtime_dependency 'railties', rails_versions
-    # 'activesupport', rails_versions
-    # 'actionpack', rails_versions
-    # 'rake', '>= 0.8.7'
+  spec.add_development_dependency 'railties', rails_versions
+  # 'activesupport', rails_versions
+  # 'actionpack', rails_versions
+  # 'rake', '>= 0.8.7'
 
   # 'activesupport', rails_versions
-    # 'i18n,
-    # 'tzinfo'
-    # 'minitest'
-    # 'thread_safe'
+  # 'i18n,
+  # 'tzinfo'
+  # 'minitest'
+  # 'thread_safe'
+
+  spec.add_runtime_dependency 'jsonapi-renderer', ['>= 0.1.1.beta1', '< 0.2']
+  spec.add_runtime_dependency 'case_transform', '>= 0.2'
 
   spec.add_development_dependency 'activerecord', rails_versions
-    # arel
-    # activesupport
-    # activemodel
+  # arel
+  # activesupport
+  # activemodel
 
   # Soft dependency for pagination
   spec.add_development_dependency 'kaminari', ' ~> 0.16.3'
@@ -54,13 +57,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.6'
   spec.add_development_dependency 'simplecov', '~> 0.11'
   spec.add_development_dependency 'timecop', '~> 0.7'
-  spec.add_development_dependency 'grape', ['>= 0.13', '< 1.0']
+  spec.add_development_dependency 'grape', ['>= 0.13', '< 0.19.1']
   spec.add_development_dependency 'json_schema'
   spec.add_development_dependency 'rake', ['>= 10.0', '< 12.0']
-
-  spec.post_install_message = <<-EOF
-NOTE: The default key case for the JsonApi adapter has changed to dashed.
-See https://github.com/rails-api/active_model_serializers/blob/master/docs/general/key_transforms.md
-for more information on configuring this behavior.
-EOF
 end

data/appveyor.yml

@@ -1,4 +1,4 @@
-version: '{build}'
+version: 1.0.{build}-{branch}
 
 skip_tags: true
 
@@ -7,17 +7,23 @@ environment:
   matrix:
     - ruby_version: "Ruby21"
     - ruby_version: "Ruby21-x64"
-    - ruby_version: "jruby-9.0.0.0"
 
 cache:
   - vendor/bundle
 
 install:
   - SET PATH=C:\%ruby_version%\bin;%PATH%
-  - gem install bundler
+  - gem update --system
+  - gem uninstall bundler -a -x
+  - gem install bundler -v 1.13.7
   - bundle env
   - bundle install --path=vendor/bundle --retry=3 --jobs=3
 
+before_test:
+  - ruby -v
+  - gem -v
+  - bundle -v
+
 test_script:
   - bundle exec rake ci
 

data/bin/rubocop

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+#
+# Usage:
+#   bin/rubocop [-A|-t|-h]
+#   bin/rubocop [file or path] [cli options]
+#
+# Options:
+#  Autocorrect    -A
+#  AutoGenConfig  -t
+#  Usage          -h,--help,help
+
+set -e
+
+case $1 in
+  -A)
+     echo "Rubocop autocorrect is ON" >&2
+     bundle exec rake -f lib/tasks/rubocop.rake rubocop:auto_correct
+     ;;
+
+  -t)
+     echo "Rubocop is generating a new TODO" >&2
+     bundle exec rake -f lib/tasks/rubocop.rake rubocop:auto_gen_config
+     ;;
+
+  -h|--help|help)
+     sed -ne '/^#/!q;s/.\{1,2\}//;1d;p' < "$0"
+     ;;
+
+  *)
+     # with no args, run vanilla rubocop
+     # else assume we're passing in arbitrary arguments
+     if [ -z "$1" ]; then
+       bundle exec rake -f lib/tasks/rubocop.rake rubocop
+     else
+       bundle exec rubocop "$@"
+     fi
+     ;;
+esac

data/docs/README.md

@@ -18,16 +18,17 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - JSON API
   - [Schema](jsonapi/schema.md)
   - [Errors](jsonapi/errors.md)
-- [ARCHITECTURE](ARCHITECTURE.md)
 
 ## How to
 
 - [How to add root key](howto/add_root_key.md)
 - [How to add pagination links](howto/add_pagination_links.md)
+- [How to add relationship links](howto/add_relationship_links.md)
 - [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
 - [Testing ActiveModelSerializers](howto/test.md)
 - [Passing Arbitrary Options](howto/passing_arbitrary_options.md)
 - [How to serialize a Plain-Old Ruby Object (PORO)](howto/serialize_poro.md)
+- [How to upgrade from `0.8` to `0.10` safely](howto/upgrade_from_0_8_to_0_10.md)
 
 ## Integrations
 

data/docs/general/adapters.md

@@ -67,9 +67,11 @@ Doesn't follow any specific convention.
 
 ### JSON
 
-The response document always with a root key.
+The json response is always rendered with a root key.
 
-The root key **can't be overridden**, and will be derived from the resource being serialized.
+The root key can be overridden by:
+* passing the `root` option in the render call. See details in the [Rendering Guides](rendering.md#overriding-the-root-key).
+* setting the `type` of the serializer. See details in the [Serializers Guide](serializers.md#type).
 
 Doesn't follow any specific convention.
 
@@ -139,18 +141,25 @@ This adapter follows **version 1.0** of the [format specified](../jsonapi/schema
 }
 ```
 
-#### Included
+### Include option
 
-It will include the associated resources in the `"included"` member
-when the resource names are included in the `include` option.
-Including nested associated resources is also supported.
+Which [serializer associations](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/serializers.md#associations) are rendered can be specified using the `include` option. The option usage is consistent with [the include option in the JSON API spec](http://jsonapi.org/format/#fetching-includes), and is available in all adapters.
 
+Example of the usage:
 ```ruby
   render json: @posts, include: ['author', 'comments', 'comments.author']
   # or
   render json: @posts, include: 'author,comments,comments.author'
 ```
 
+The format of the `include` option can be either:
+
+- a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes).
+- an Array of Symbols and Hashes.
+- a mix of both.
+
+An empty string or an empty array will prevent rendering of any associations.
+
 In addition, two types of wildcards may be used:
 
 - `*` includes one level of associations.
@@ -162,11 +171,6 @@ These can be combined with other paths.
   render json: @posts, include: '**' # or '*' for a single layer
 ```
 
-The format of the `include` option can be either:
-
-- a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes).
-- an Array of Symbols and Hashes.
-- a mix of both.
 
 The following would render posts and include:
 
@@ -180,6 +184,20 @@ It could be combined, like above, with other paths in any combination desired.
   render json: @posts, include: 'author.comments.**'
 ```
 
+**Note:** Wildcards are ActiveModelSerializers-specific, they are not part of the JSON API spec.
+
+The default include for the JSON API adapter is no associations. The default for the JSON and Attributes adapters is all associations.
+
+For the JSON API adapter associated resources will be gathered in the `"included"` member. For the JSON and Attributes
+adapters associated resources will be rendered among the other attributes.
+
+Only for the JSON API adapter you can specify, which attributes of associated resources will be rendered. This feature
+is called [sparse fieldset](http://jsonapi.org/format/#fetching-sparse-fieldsets):
+
+```ruby
+  render json: @posts, include: 'comments', fields: { comments: ['content', 'created_at'] }
+```
+
 ##### Security Considerations
 
 Since the included options may come from the query params (i.e. user-controller):

data/docs/general/caching.md

@@ -2,6 +2,12 @@
 
 # Caching
 
+## Warning
+
+There is currently a problem with caching in AMS [Caching doesn't improve performance](https://github.com/rails-api/active_model_serializers/issues/1586). Adding caching _may_ slow down your application, rather than speeding it up. We suggest you benchmark any caching you implement before using in a production enviroment
+
+___
+
 To cache a serializer, call ```cache``` and pass its options.
 The options are the same options of ```ActiveSupport::Cache::Store```, plus
 a ```key``` option that will be the prefix of the object cache
@@ -17,7 +23,7 @@ The cache support is optimized to use the cached object in multiple request. An
 cache(options = nil) # options: ```{key, expires_in, compress, force, race_condition_ttl}```
 ```
 
-Take the example bellow:
+Take the example below:
 
 ```ruby
 class PostSerializer < ActiveModel::Serializer

data/docs/general/configuration_options.md

@@ -46,15 +46,71 @@ Each adapter has a default key transform configured:
 
 | Adapter | Default Key Transform |
 |----|----|
+| `Attributes` | `:unaltered` |
 | `Json` | `:unaltered` |
 | `JsonApi` | `:dash` |
 
 `config.key_transform` is a global override of the adapter default. Adapters
 still prefer the render option `:key_transform` over this setting.
 
+*NOTE: Key transforms can be expensive operations. If key transforms are unnecessary for the
+application, setting `config.key_transform` to `:unaltered` will provide a performance boost.*
 
-## JSON API
+##### default_includes
+What relationships to serialize by default.  Default: `'*'`, which includes one level of related
+objects. See [includes](adapters.md#included) for more info.
+
+
+##### serializer_lookup_chain
+
+Configures how serializers are searched for. By default, the lookup chain is
+
+```ruby
+ActiveModelSerializers::LookupChain::DEFAULT
+```
+
+which is shorthand for
+
+```ruby
+[
+  ActiveModelSerializers::LookupChain::BY_PARENT_SERIALIZER,
+  ActiveModelSerializers::LookupChain::BY_NAMESPACE,
+  ActiveModelSerializers::LookupChain::BY_RESOURCE_NAMESPACE,
+  ActiveModelSerializers::LookupChain::BY_RESOURCE
+]
+```
+
+Each of the array entries represent a proc. A serializer lookup proc will be yielded 3 arguments. `resource_class`, `serializer_class`, and `namespace`.
+
+Note that:
+ - `resource_class` is the class of the resource being rendered
+ - by default `serializer_class` is `ActiveModel::Serializer`
+   - for association lookup it's the "parent" serializer
+ - `namespace` correspond to either the controller namespace or the [optionally] specified [namespace render option](./rendering.md#namespace)
+
+An example config could be:
+
+```ruby
+ActiveModelSerializers.config.serializer_lookup_chain = [
+  lambda do |resource_class, serializer_class, namespace|
+    "API::#{namespace}::#{resource_class}"
+  end
+]
+```
 
+If you simply want to add to the existing lookup_chain. Use `unshift`.
+
+```ruby
+ActiveModelSerializers.config.serializer_lookup_chain.unshift(
+  lambda do |resource_class, serializer_class, namespace|
+    # ...
+  end
+)
+```
+
+See [lookup_chain.rb](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/lookup_chain.rb) for further explanations and examples.
+
+## JSON API
 
 ##### jsonapi_resource_type
 
@@ -67,6 +123,19 @@ Possible values:
 - `:singular`
 - `:plural` (default)
 
+##### jsonapi_namespace_separator
+
+Sets separator string for namespaced models to render `type` attribute.
+
+
+| Separator | Example: Admin::User |
+|----|----|
+| `'-'` (default) | 'admin-users'
+| `'--'` (recommended) | 'admin--users'
+
+See [Recommendation for dasherizing (kebab-case-ing) namespaced object, such as `Admin::User`](https://github.com/json-api/json-api/issues/850)
+for more discussion.
+
 ##### jsonapi_include_toplevel_object
 
 Include a [top level jsonapi member](http://jsonapi.org/format/#document-jsonapi-object)

data/docs/general/deserialization.md

@@ -42,7 +42,7 @@ document = {
       'title' => 'Title 1',
       'date' => '2015-12-20'
     },
-    'associations' => {
+    'relationships' => {
       'author' => {
         'data' => {
           'type' => 'user',

data/docs/general/fields.md

@@ -0,0 +1,31 @@
+[Back to Guides](../README.md)
+
+# Fields
+
+If for any reason, you need to restrict the fields returned, you should use `fields` option.
+
+For example, if you have a serializer like this
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  attributes :access_token, :first_name, :last_name
+end
+```
+
+and in a specific controller, you want to return `access_token` only, `fields` will help you:
+
+```ruby
+class AnonymousController < ApplicationController
+  def create
+    render json: User.create(activation_state: 'anonymous'), fields: [:access_token], status: 201
+  end
+end
+```
+
+Note that this is only valid for the `json` and `attributes` adapter. For the `json_api` adapter, you would use
+
+```ruby
+render json: @user, fields: { users: [:access_token] }
+```
+
+Where `users` is the JSONAPI type.

data/docs/general/getting_started.md

@@ -37,7 +37,7 @@ and
 class CommentSerializer < ActiveModel::Serializer
   attributes :name, :body
 
-  belongs_to :post_id
+  belongs_to :post
 end
 ```
 

data/docs/general/logging.md

@@ -12,3 +12,10 @@ You may customize the logger in an initializer, for example:
 ```ruby
 ActiveModelSerializers.logger = Logger.new(STDOUT)
 ```
+
+You can also disable the logger, just put this in `config/initializers/active_model_serializers.rb`:
+
+```ruby
+require 'active_model_serializers'
+ActiveSupport::Notifications.unsubscribe(ActiveModelSerializers::Logging::RENDER_EVENT)
+```

data/docs/general/rendering.md

@@ -48,42 +48,36 @@ render json: @posts, serializer: CollectionSerializer, each_serializer: PostPrev
 
 ## Serializing non-ActiveRecord objects
 
-All serializable resources must pass the
-[ActiveModel::Serializer::Lint::Tests](../../lib/active_model/serializer/lint.rb#L17).
-
-See the ActiveModelSerializers::Model for a base class that implements the full
-API for a plain-old Ruby object (PORO).
+See [README](../../README.md#what-does-a-serializable-resource-look-like)
 
 ## SerializableResource options
 
-The `options` hash passed to `render` or `ActiveModelSerializers::SerializableResource.new(resource, options)`
-are partitioned into `serializer_opts` and `adapter_opts`. `adapter_opts` are passed to new Adapters;
-`serializer_opts` are passed to new Serializers.
-
-The `adapter_opts` are specified in [ActiveModelSerializers::SerializableResource::ADAPTER_OPTIONS](../../lib/active_model_serializers/serializable_resource.rb#L5).
-The `serializer_opts` are the remaining options.
-
-(In Rails, the `options` are also passed to the `as_json(options)` or `to_json(options)`
-methods on the resource serialization by the Rails JSON renderer.  They are, therefore, important
-to know about, but not part of ActiveModelSerializers.)
-
-See [ARCHITECTURE](../ARCHITECTURE.md) for more information.
+See [README](../../README.md#activemodelserializersserializableresource)
 
 ### adapter_opts
 
 #### fields
 
-PR please :)
+If you are using `json` or `attributes` adapter
+```ruby
+render json: @user, fields: [:access_token]
+```
+
+See [Fields](fields.md) for more information.
 
 #### adapter
 
-PR please :)
+This option lets you explicitly set the adapter to be used by passing a registered adapter. Your options are `:attributes`, `:json`, and `:json_api`.
+
+```
+ActiveModel::Serializer.config.adapter = :json_api
+```
 
 #### key_transform
 
 ```render json: posts, each_serializer: PostSerializer, key_transform: :camel_lower```
 
-See [Key Transforms](key_transforms.md) for more informaiton.
+See [Key Transforms](key_transforms.md) for more information.
 
 #### meta
 
@@ -209,7 +203,7 @@ link(:link_name) { url_for(controller: 'controller_name', action: 'index', only_
 
 #### include
 
-PR please :)
+See [Adapters: Include Option](/docs/general/adapters.md#include-option).
 
 #### Overriding the root key
 
@@ -234,17 +228,61 @@ This will be rendered as:
 ```
 Note: the `Attributes` adapter (default) does not include a resource root. You also will not be able to create a single top-level root if you are using the :json_api adapter.
 
+#### namespace
+
+The namespace for serializer lookup is based on the controller.
+
+To configure the implicit namespace, in your controller, create a before filter
+
+```ruby
+before_action do
+  self.namespace_for_serializer = Api::V2
+end
+```
+
+`namespace` can also be passed in as a render option:
+
+
+```ruby
+@post = Post.first
+render json: @post, namespace: Api::V2
+```
+
+This tells the serializer lookup to check for the existence of `Api::V2::PostSerializer`, and if any relations are rendered with `@post`, they will also utilize the `Api::V2` namespace.  
+
+The `namespace` can be any object whose namespace can be represented by string interpolation (i.e. by calling to_s)
+- Module `Api::V2`
+- String `'Api::V2'`
+- Symbol `:'Api::V2'`
+
+Note that by using a string and symbol, Ruby will assume the namespace is defined at the top level.
+
+
 #### serializer
 
-PR please :)
+Specify which serializer to use if you want to use a serializer other than the default.
+
+For a single resource:
+
+```ruby
+@post = Post.first
+render json: @post, serializer: SpecialPostSerializer
+```
+
+To specify which serializer to use on individual items in a collection (i.e., an `index` action), use `each_serializer`:
+
+```ruby
+@posts = Post.all
+render json: @posts, each_serializer: SpecialPostSerializer
+```
 
 #### scope
 
-PR please :)
+See [Serializers: Scope](/docs/general/serializers.md#scope).
 
 #### scope_name
 
-PR please :)
+See [Serializers: Scope](/docs/general/serializers.md#scope).
 
 ## Using a serializer without `render`