Merge branch 'master' into 0-10-stable

Author: bf4

.rubocop.yml

@@ -1,10 +1,13 @@
 AllCops:
   TargetRubyVersion: 2.1
   Exclude:
-    - config/initializers/forbidden_yaml.rb
     - !ruby/regexp /(vendor|bundle|bin|db|tmp)\/.*/
   DisplayCopNames: true
   DisplayStyleGuide: true
+  # https://github.com/bbatsov/rubocop/blob/master/manual/caching.md
+  # https://github.com/bbatsov/rubocop/blob/e8680418b351491e111a18cf5b453fc07a3c5239/config/default.yml#L60-L77
+  UseCache: true
+  CacheRootDirectory: tmp
 
 Rails:
   Enabled: true

CHANGELOG.md

@@ -1,6 +1,6 @@
 ## 0.10.x
 
-### [master (unreleased)](https://github.com/rails-api/active_model_serializers/compare/v0.10.5...master)
+### [master (unreleased)](https://github.com/rails-api/active_model_serializers/compare/v0.10.6...master)
 
 Breaking changes:
 
@@ -14,6 +14,20 @@ Fixes:
 
 Misc:
 
+### [v0.10.6 (2017-05-01)](https://github.com/rails-api/active_model_serializers/compare/v0.10.5...v0.10.6)
+
+Fixes:
+
+- [#1857](https://github.com/rails-api/active_model_serializers/pull/1857) JSON:API does not load belongs_to relation to get identifier id. (@bf4)
+- [#2119](https://github.com/rails-api/active_model_serializers/pull/2119) JSON:API returns null resource object identifier when 'id' is null. (@bf4)
+- [#2093](https://github.com/rails-api/active_model_serializers/pull/2093) undef problematic Serializer methods: display, select. (@bf4)
+
+Misc:
+
+- [#2104](https://github.com/rails-api/active_model_serializers/pull/2104) Documentation for serializers and rendering. (@cassidycodes)
+- [#2081](https://github.com/rails-api/active_model_serializers/pull/2081) Documentation for `include` option in adapters. (@charlie-wasp)
+- [#2120](https://github.com/rails-api/active_model_serializers/pull/2120) Documentation for association options: foreign_key, type, class_name, namespace. (@bf4)
+
 ### [v0.10.5 (2017-03-07)](https://github.com/rails-api/active_model_serializers/compare/v0.10.4...v0.10.5)
 
 Breaking changes:
@@ -81,7 +95,7 @@ Misc:
 
 - [#1878](https://github.com/rails-api/active_model_serializers/pull/1878) Cache key generation for serializers now uses `ActiveSupport::Cache.expand_cache_key` instead of `Array#join` by default and is also overridable. This change should be backward-compatible. (@markiz)
 
-- [#1799](https://github.com/rails-api/active_model_serializers/pull/1799) Add documentation for setting the adapter. (@ScottKbka)
+- [#1799](https://github.com/rails-api/active_model_serializers/pull/1799) Add documentation for setting the adapter. (@cassidycodes)
 - [#1909](https://github.com/rails-api/active_model_serializers/pull/1909) Add documentation for relationship links. (@vasilakisfil, @NullVoxPopuli)
 - [#1959](https://github.com/rails-api/active_model_serializers/pull/1959) Add documentation for root. (@shunsuke227ono)
 - [#1967](https://github.com/rails-api/active_model_serializers/pull/1967) Improve type method documentation. (@yukideluxe)

README.md

@@ -90,8 +90,8 @@ reading documentation for our `master`, which may include features that have not
 been released yet. Please see below for the documentation relevant to you.
 
 - [0.10 (master) Documentation](https://github.com/rails-api/active_model_serializers/tree/master)
-- [0.10.4 (latest release) Documentation](https://github.com/rails-api/active_model_serializers/tree/v0.10.4)
-  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/active_model_serializers/0.10.4)
+- [0.10.6 (latest release) Documentation](https://github.com/rails-api/active_model_serializers/tree/v0.10.6)
+  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/active_model_serializers/0.10.6)
   - [Guides](docs)
 - [0.9 (0-9-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-9-stable)
   - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/0-9-stable)

Rakefile

@@ -7,6 +7,7 @@ begin
   require 'simplecov'
 rescue LoadError # rubocop:disable Lint/HandleExceptions
 end
+import('lib/tasks/rubocop.rake')
 
 Bundler::GemHelper.install_tasks
 
@@ -30,36 +31,6 @@ namespace :yard do
   end
 end
 
-begin
-  require 'rubocop'
-  require 'rubocop/rake_task'
-rescue LoadError # rubocop:disable Lint/HandleExceptions
-else
-  Rake::Task[:rubocop].clear if Rake::Task.task_defined?(:rubocop)
-  require 'rbconfig'
-  # https://github.com/bundler/bundler/blob/1b3eb2465a/lib/bundler/constants.rb#L2
-  windows_platforms = /(msdos|mswin|djgpp|mingw)/
-  if RbConfig::CONFIG['host_os'] =~ windows_platforms
-    desc 'No-op rubocop on Windows-- unsupported platform'
-    task :rubocop do
-      puts 'Skipping rubocop on Windows'
-    end
-  elsif defined?(::Rubinius)
-    desc 'No-op rubocop to avoid rbx segfault'
-    task :rubocop do
-      puts 'Skipping rubocop on rbx due to segfault'
-      puts 'https://github.com/rubinius/rubinius/issues/3499'
-    end
-  else
-    Rake::Task[:rubocop].clear if Rake::Task.task_defined?(:rubocop)
-    desc 'Execute rubocop'
-    RuboCop::RakeTask.new(:rubocop) do |task|
-      task.options = ['--rails', '--display-cop-names', '--display-style-guide']
-      task.fail_on_error = true
-    end
-  end
-end
-
 require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|

active_model_serializers.gemspec

@@ -57,7 +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']
 end

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

docs/general/adapters.md

@@ -141,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.
@@ -164,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:
 
@@ -182,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):

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

docs/general/rendering.md

@@ -203,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
 
@@ -260,15 +260,29 @@ Note that by using a string and symbol, Ruby will assume the namespace is define
 
 #### 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`
 

docs/general/serializers.md

@@ -64,6 +64,10 @@ Where:
   - `unless:`
   - `virtual_value:`
   - `polymorphic:` defines if polymorphic relation type should be nested in serialized association.
+  - `type:` the resource type as used by JSON:API, especially on a `belongs_to` relationship.
+  - `class_name:` used to determine `type` when `type` not given
+  - `foreign_key:` used by JSON:API on a `belongs_to` relationship to avoid unnecessarily loading the association object.
+  - `namespace:` used when looking up the serializer and `serializer` is not given.  Falls back to the parent serializer's `:namespace` instance options, which, when present, comes from the render options. See [Rendering#namespace](rendering.md#namespace] for more details.
 - optional: `&block` is a context that returns the association's attributes.
   - prevents `association_name` method from being called.
   - return value of block is used as the association value.
@@ -382,11 +386,26 @@ The serialized value for a given key. e.g. `read_attribute_for_serialization(:ti
 
 #### #links
 
-PR please :)
+Allows you to modify the `links` node. By default, this node will be populated with the attributes set using the [::link](#link) method. Using `links: nil` will remove the `links` node.
+
+```ruby
+ActiveModelSerializers::SerializableResource.new(
+  @post,
+  adapter: :json_api,
+  links: {
+    self: {
+      href: 'http://example.com/posts',
+      meta: {
+        stuff: 'value'
+      }
+    }
+  }
+)
+```
 
 #### #json_key
 
-PR please :)
+Returns the key used by the adapter as the resource root. See [root](#root) for more information.
 
 ## Examples