active_model_serializers 0.10.2 → 0.10.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. checksums.yaml +4 -4
  2. data/.travis.yml +8 -1
  3. data/CHANGELOG.md +45 -3
  4. data/CODE_OF_CONDUCT.md +74 -0
  5. data/Gemfile +4 -1
  6. data/README.md +5 -2
  7. data/active_model_serializers.gemspec +2 -2
  8. data/docs/ARCHITECTURE.md +6 -7
  9. data/docs/README.md +2 -0
  10. data/docs/general/caching.md +7 -1
  11. data/docs/general/configuration_options.md +64 -0
  12. data/docs/general/rendering.md +35 -1
  13. data/docs/general/serializers.md +35 -5
  14. data/docs/howto/add_pagination_links.md +2 -2
  15. data/docs/howto/add_relationship_links.md +137 -0
  16. data/docs/howto/add_root_key.md +4 -0
  17. data/docs/howto/grape_integration.md +42 -0
  18. data/docs/howto/outside_controller_use.md +9 -2
  19. data/docs/howto/passing_arbitrary_options.md +2 -2
  20. data/docs/howto/test.md +2 -0
  21. data/docs/howto/upgrade_from_0_8_to_0_10.md +265 -0
  22. data/docs/integrations/ember-and-json-api.md +41 -24
  23. data/lib/action_controller/serialization.rb +9 -0
  24. data/lib/active_model/serializer.rb +19 -22
  25. data/lib/active_model/serializer/association.rb +19 -4
  26. data/lib/active_model/serializer/collection_serializer.rb +8 -5
  27. data/lib/active_model/serializer/{associations.rb → concerns/associations.rb} +8 -5
  28. data/lib/active_model/serializer/{attributes.rb → concerns/attributes.rb} +0 -0
  29. data/lib/active_model/serializer/{caching.rb → concerns/caching.rb} +5 -1
  30. data/lib/active_model/serializer/{configuration.rb → concerns/configuration.rb} +24 -1
  31. data/lib/active_model/serializer/{links.rb → concerns/links.rb} +0 -0
  32. data/lib/active_model/serializer/{meta.rb → concerns/meta.rb} +0 -0
  33. data/lib/active_model/serializer/{type.rb → concerns/type.rb} +0 -0
  34. data/lib/active_model/serializer/reflection.rb +37 -21
  35. data/lib/active_model/serializer/version.rb +1 -1
  36. data/lib/active_model_serializers.rb +1 -0
  37. data/lib/active_model_serializers/adapter/attributes.rb +3 -1
  38. data/lib/active_model_serializers/adapter/json_api.rb +15 -22
  39. data/lib/active_model_serializers/adapter/json_api/relationship.rb +30 -19
  40. data/lib/active_model_serializers/adapter/json_api/resource_identifier.rb +23 -9
  41. data/lib/active_model_serializers/key_transform.rb +4 -0
  42. data/lib/active_model_serializers/lookup_chain.rb +80 -0
  43. data/lib/active_model_serializers/model.rb +1 -1
  44. data/lib/active_model_serializers/serializable_resource.rb +6 -5
  45. data/lib/generators/rails/serializer_generator.rb +1 -1
  46. data/test/action_controller/json_api/fields_test.rb +57 -0
  47. data/test/action_controller/json_api/transform_test.rb +3 -3
  48. data/test/action_controller/lookup_proc_test.rb +49 -0
  49. data/test/action_controller/namespace_lookup_test.rb +226 -0
  50. data/test/active_model_serializers/key_transform_test.rb +32 -0
  51. data/test/active_model_serializers/model_test.rb +11 -0
  52. data/test/adapter/attributes_test.rb +43 -0
  53. data/test/adapter/json/transform_test.rb +1 -1
  54. data/test/adapter/json_api/fields_test.rb +4 -3
  55. data/test/adapter/json_api/has_many_test.rb +21 -0
  56. data/test/adapter/json_api/include_data_if_sideloaded_test.rb +166 -0
  57. data/test/adapter/json_api/linked_test.rb +24 -6
  58. data/test/adapter/json_api/links_test.rb +1 -1
  59. data/test/adapter/json_api/pagination_links_test.rb +17 -2
  60. data/test/adapter/json_api/relationship_test.rb +309 -73
  61. data/test/adapter/json_api/resource_identifier_test.rb +20 -0
  62. data/test/adapter/json_api/transform_test.rb +4 -3
  63. data/test/benchmark/benchmarking_support.rb +1 -1
  64. data/test/benchmark/bm_active_record.rb +81 -0
  65. data/test/benchmark/bm_adapter.rb +38 -0
  66. data/test/benchmark/bm_caching.rb +1 -1
  67. data/test/benchmark/bm_lookup_chain.rb +83 -0
  68. data/test/cache_test.rb +42 -4
  69. data/test/collection_serializer_test.rb +1 -1
  70. data/test/fixtures/poro.rb +44 -41
  71. data/test/generators/serializer_generator_test.rb +22 -5
  72. data/test/serializers/association_macros_test.rb +3 -2
  73. data/test/serializers/associations_test.rb +97 -22
  74. data/test/serializers/attribute_test.rb +1 -1
  75. data/test/serializers/serializer_for_test.rb +3 -3
  76. data/test/serializers/serializer_for_with_namespace_test.rb +87 -0
  77. data/test/support/serialization_testing.rb +16 -0
  78. data/test/test_helper.rb +1 -0
  79. metadata +35 -14
  80. data/test/adapter/json_api/relationships_test.rb +0 -204
@@ -10,9 +10,9 @@ the resource is paginated and if you are using the ```JsonApi``` adapter.
10
10
  If you want pagination links in your response, use [Kaminari](https://github.com/amatsuda/kaminari)
11
11
  or [WillPaginate](https://github.com/mislav/will_paginate).
12
12
 
13
- Although the others adapters does not have this feature, it is possible to
13
+ Although the other adapters do not have this feature, it is possible to
14
14
  implement pagination links to `JSON` adapter. For more information about it,
15
- please see in our docs
15
+ please check our docs.
16
16
 
17
17
  ###### Kaminari examples
18
18
 
@@ -0,0 +1,137 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # How to add relationship links
4
+
5
+ ActiveModelSerializers offers you many ways to add links in your JSON, depending on your needs.
6
+ The most common use case for links is supporting nested resources.
7
+
8
+ The following examples are without included relationship data (`include` param is empty),
9
+ specifically the following Rails controller was used for these examples:
10
+
11
+ ```ruby
12
+ class Api::V1::UsersController < ApplicationController
13
+ def show
14
+ render jsonapi: User.find(params[:id]),
15
+ serializer: Api::V1::UserSerializer,
16
+ include: []
17
+ end
18
+ ```
19
+
20
+ Bear in mind though that ActiveModelSerializers are [framework-agnostic](outside_controller_use.md), Rails is just a common example here.
21
+
22
+ ### Links as an attribute of a resource
23
+ **This is applicable to JSONAPI, JSON and Attributes adapters**
24
+
25
+ You can define an attribute in the resource, named `links`.
26
+
27
+ ```ruby
28
+ class Api::V1::UserSerializer < ActiveModel::Serializer
29
+ attributes :id, :name, :links
30
+
31
+ def links
32
+ {
33
+ self: api_v1_user_path(object.id),
34
+ microposts: api_v1_microposts_path(user_id: object.id)
35
+ }
36
+ end
37
+ end
38
+ ```
39
+
40
+ This will resilt in (example is in jsonapi adapter):
41
+ ```json
42
+ {
43
+ "data": {
44
+ "id": "1",
45
+ "type": "users",
46
+ "attributes": {
47
+ "name": "Example User",
48
+ "links": {
49
+ "self": "/api/v1/users/1",
50
+ "microposts": "/api/v1/microposts?user_id=1"
51
+ }
52
+ }
53
+ }
54
+ }
55
+ ```
56
+
57
+
58
+ ### Links as a property of the resource definiton
59
+ **This is only applicable to JSONAPI adapter**
60
+
61
+ You can use the `links` class method to define the links you need in the resource's primary data.
62
+
63
+ ```ruby
64
+ class Api::V1::UserSerializer < ActiveModel::Serializer
65
+ attributes :id, :name
66
+
67
+ link(:self) { api_v1_user_path(object.id) }
68
+ link(:microposts) { api_v1_microposts_path(user_id: object.id) }
69
+ end
70
+ ```
71
+
72
+ This will resilt in (example is in jsonapi adapter):
73
+ ```json
74
+ {
75
+ "data": {
76
+ "id": "1",
77
+ "type": "users",
78
+ "attributes": {
79
+ "name": "Example User"
80
+ },
81
+ "links": {
82
+ "self": "/api/v1/users/1",
83
+ "microposts": "/api/v1/microposts?user_id=1"
84
+ }
85
+ }
86
+ }
87
+ ```
88
+
89
+ ### Links that follow the JSONAPI spec
90
+ **This is only applicable to JSONAPI adapter**
91
+
92
+ If you have a JSONAPI-strict client that you are working with (like `ember-data`)
93
+ you need to construct the links inside the relationships. Also the link to fetch the
94
+ relationship data must be under the `related` attribute, whereas to manipulate the
95
+ relationship (in case of many-to-many relationship) must be under the `self` attribute.
96
+
97
+ You can find more info in the [spec](http://jsonapi.org/format/#document-resource-object-relationships).
98
+
99
+ Here is how you can do this:
100
+
101
+ ```ruby
102
+ class Api::V1::UserSerializer < ActiveModel::Serializer
103
+ attributes :id, :name
104
+
105
+ has_many :microposts, serializer: Api::V1::MicropostSerializer do
106
+ link(:related) { api_v1_microposts_path(user_id: object.id) }
107
+ end
108
+
109
+ #this is needed to avoid n+1, gem core devs are working to remove this necessity
110
+ #more on: https://github.com/rails-api/active_model_serializers/issues/1325
111
+ def microposts
112
+ object.microposts.loaded ? object.microposts : object.microposts.none
113
+ end
114
+ end
115
+ ```
116
+
117
+ This will result in:
118
+
119
+ ```json
120
+ {
121
+ "data": {
122
+ "id": "1",
123
+ "type": "users",
124
+ "attributes": {
125
+ "name": "Example User"
126
+ },
127
+ "relationships": {
128
+ "microposts": {
129
+ "data": [],
130
+ "links": {
131
+ "related": "/api/v1/microposts?user_id=1"
132
+ }
133
+ }
134
+ }
135
+ }
136
+ }
137
+ ```
@@ -1,3 +1,5 @@
1
+ [Back to Guides](../README.md)
2
+
1
3
  # How to add root key
2
4
 
3
5
  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:
@@ -49,3 +51,5 @@ or if it returns a collection:
49
51
  ]
50
52
  }
51
53
  ```
54
+
55
+ [There are several ways to specify root](../general/serializers.md#root) when using the JSON adapter.
@@ -0,0 +1,42 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ 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.
4
+
5
+ In the simpliest way:
6
+
7
+ ```
8
+ class API < Grape::API
9
+ # @note Make sure this is above you're first +mount+
10
+ use Grape::Middleware::Globals
11
+ end
12
+ ```
13
+
14
+ or more like what is shown in current Grape tutorials:
15
+
16
+ ```
17
+ module MyApi
18
+ class ApiBase < Grape::API
19
+ use Grape::Middleware::Globals
20
+
21
+ require 'grape/active_model_serializers'
22
+ include Grape::ActiveModelSerializers
23
+
24
+ mount MyApi::V1::ApiBase
25
+ end
26
+ end
27
+ ```
28
+
29
+ You could meet this dependency with your own middleware. The invocation might look like:
30
+
31
+ ```
32
+ module MyApi
33
+ class ApiBase < Grape::API
34
+ use My::Middleware::Thingamabob
35
+
36
+ require 'grape/active_model_serializers'
37
+ include Grape::ActiveModelSerializers
38
+
39
+ mount MyApi::V1::ApiBase
40
+ end
41
+ end
42
+ ```
@@ -19,10 +19,11 @@ serializable_resource = ActiveModelSerializers::SerializableResource.new(post, o
19
19
  # Convert your resource into json
20
20
  model_json = serializable_resource.as_json
21
21
  ```
22
+ The object that is passed to `ActiveModelSerializers::SerializableResource.new` can be a single resource or a collection.
22
23
 
23
24
  ### Looking up the Serializer for a Resource
24
25
 
25
- If you want to retrieve a serializer for a specific resource, you can do the following:
26
+ If you want to retrieve the serializer class for a specific resource, you can do the following:
26
27
 
27
28
  ```ruby
28
29
  # Create our resource
@@ -41,7 +42,13 @@ You could also retrieve the serializer via:
41
42
  ActiveModelSerializers::SerializableResource.new(post, options).serializer
42
43
  ```
43
44
 
44
- Both approaches will return an instance, if any, of the resource's serializer.
45
+ Both approaches will return the serializer class that will be used for the resource.
46
+
47
+ Additionally, you could retrieve the serializer instance for the resource via:
48
+
49
+ ```ruby
50
+ ActiveModelSerializers::SerializableResource.new(post, options).serializer_instance
51
+ ```
45
52
 
46
53
  ## Serializing before controller render
47
54
 
@@ -11,7 +11,7 @@ For example, we could pass in a field, such as `user_id` into our serializer.
11
11
  ```ruby
12
12
  # posts_controller.rb
13
13
  class PostsController < ApplicationController
14
- def dashboard
14
+ def dashboard
15
15
  render json: @post, user_id: 12
16
16
  end
17
17
  end
@@ -20,7 +20,7 @@ end
20
20
  class PostSerializer < ActiveModel::Serializer
21
21
  attributes :id, :title, :body
22
22
 
23
- def comments_by_me
23
+ def comments_by_me
24
24
  Comments.where(user_id: instance_options[:user_id], post_id: object.id)
25
25
  end
26
26
  end
@@ -1,3 +1,5 @@
1
+ [Back to Guides](../README.md)
2
+
1
3
  # How to test
2
4
 
3
5
  ## Controller Serializer Usage
@@ -0,0 +1,265 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # How to migrate from `0.8` to `0.10` safely
4
+
5
+ ## Disclaimer
6
+ ### Proceed at your own risk
7
+ This document attempts to outline steps to upgrade your app based on the collective experience of
8
+ developers who have done this already. It may not cover all edge cases and situations that may cause issues,
9
+ so please proceed with a certain level of caution.
10
+
11
+ ## Overview
12
+ This document outlines the steps needed to migrate from `0.8` to `0.10`. The method described
13
+ below has been created via the collective knowledge of contributions of those who have done
14
+ the migration successfully. The method has been tested specifically for migrating from `0.8.3`
15
+ to `0.10.2`.
16
+
17
+ The high level approach is to upgrade to `0.10` and change all serializers to use
18
+ a backwards-compatible `ActiveModel::V08::Serializer`or `ActiveModel::V08::CollectionSerializer`
19
+ and a `ActiveModelSerializers::Adapter::V08Adapter`. After a few more manual changes, you should have the same
20
+ functionality as you had with `AMS 0.8`. Then, you can continue to develop in your app by creating
21
+ new serializers that don't use these backwards compatible versions and slowly migrate
22
+ existing serializers to the `0.10` versions as needed.
23
+
24
+ ### `0.10` breaking changes
25
+ - Passing a serializer to `render json:` is no longer supported
26
+
27
+ ```ruby
28
+ render json: CustomerSerializer.new(customer) # rendered in 0.8, errors in 0.10
29
+ ```
30
+
31
+ - Passing a nil resource to serializer now fails
32
+
33
+ ```ruby
34
+ CustomerSerializer.new(nil) # returned nil in 0.8, throws error in 0.10
35
+ ```
36
+
37
+ - Attribute methods are no longer defined on the serializer, and must be explicitly
38
+ accessed through `object`
39
+
40
+ ```ruby
41
+ class MySerializer
42
+ attributes :foo, :bar
43
+
44
+ def foo
45
+ bar + 1 # bar does not work, needs to be object.bar in 0.10
46
+ end
47
+ end
48
+ ```
49
+
50
+ - `root` option to collection serializer behaves differently
51
+
52
+ ```ruby
53
+ # in 0.8
54
+ ActiveModel::ArraySerializer.new(resources, root: "resources")
55
+ # resulted in { "resources": <serialized_resources> }, does not work in 0.10
56
+ ```
57
+
58
+ - No default serializer when serializer doesn't exist
59
+ - `@options` changed to `instance_options`
60
+ - Nested relationships are no longer walked by default. Use the `:include` option at **controller `render`** level to specify what relationships to walk. E.g. `render json: @post, include: {comments: :author}` if you want the `author` relationship walked, otherwise the json would only include the post with comments. See: https://github.com/rails-api/active_model_serializers/pull/1127
61
+ - To emulate `0.8`'s walking of arbitrarily deep relationships use: `include: '**'`. E.g. `render json: @post, include: '**'`
62
+
63
+ ## Steps to migrate
64
+
65
+ ### 1. Upgrade the `active_model_serializer` gem in you `Gemfile`
66
+ Change to `gem 'active_model_serializers', '~> 0.10'` and run `bundle install`
67
+
68
+ ### 2. Add `ActiveModel::V08::Serializer`
69
+
70
+ ```ruby
71
+ module ActiveModel
72
+ module V08
73
+ class Serializer < ActiveModel::Serializer
74
+ include Rails.application.routes.url_helpers
75
+
76
+ # AMS 0.8 would delegate method calls from within the serializer to the
77
+ # object.
78
+ def method_missing(*args)
79
+ method = args.first
80
+ read_attribute_for_serialization(method)
81
+ end
82
+
83
+ alias_method :options, :instance_options
84
+
85
+ # Since attributes could be read from the `object` via `method_missing`,
86
+ # the `try` method did not behave as before. This patches `try` with the
87
+ # original implementation plus the addition of
88
+ # ` || object.respond_to?(a.first, true)` to check if the object responded to
89
+ # the given method.
90
+ def try(*a, &b)
91
+ if a.empty? || respond_to?(a.first, true) || object.respond_to?(a.first, true)
92
+ try!(*a, &b)
93
+ end
94
+ end
95
+
96
+ # AMS 0.8 would return nil if the serializer was initialized with a nil
97
+ # resource.
98
+ def serializable_hash(adapter_options = nil,
99
+ options = {},
100
+ adapter_instance =
101
+ self.class.serialization_adapter_instance)
102
+ object.nil? ? nil : super
103
+ end
104
+ end
105
+ end
106
+ end
107
+
108
+ ```
109
+ Add this class to your app however you see fit. This is the class that your existing serializers
110
+ that inherit from `ActiveMode::Serializer` should inherit from.
111
+
112
+ ### 3. Add `ActiveModel::V08::CollectionSerializer`
113
+ ```ruby
114
+ module ActiveModel
115
+ module V08
116
+ class CollectionSerializer < ActiveModel::Serializer::CollectionSerializer
117
+ # In AMS 0.8, passing an ArraySerializer instance with a `root` option
118
+ # properly nested the serialized resources within the given root.
119
+ # Ex.
120
+ #
121
+ # class MyController < ActionController::Base
122
+ # def index
123
+ # render json: ActiveModel::Serializer::ArraySerializer
124
+ # .new(resources, root: "resources")
125
+ # end
126
+ # end
127
+ #
128
+ # Produced
129
+ #
130
+ # {
131
+ # "resources": [
132
+ # <serialized_resource>,
133
+ # ...
134
+ # ]
135
+ # }
136
+ def as_json(options = {})
137
+ if root
138
+ {
139
+ root => super
140
+ }
141
+ else
142
+ super
143
+ end
144
+ end
145
+
146
+ # AMS 0.8 used `DefaultSerializer` if it couldn't find a serializer for
147
+ # the given resource. When not using an adapter, this is not true in
148
+ # `0.10`
149
+ def serializer_from_resource(resource, serializer_context_class, options)
150
+ serializer_class =
151
+ options.fetch(:serializer) { serializer_context_class.serializer_for(resource) }
152
+
153
+ if serializer_class.nil? # rubocop:disable Style/GuardClause
154
+ DefaultSerializer.new(resource, options)
155
+ else
156
+ serializer_class.new(resource, options.except(:serializer))
157
+ end
158
+ end
159
+
160
+ class DefaultSerializer
161
+ attr_reader :object, :options
162
+
163
+ def initialize(object, options={})
164
+ @object, @options = object, options
165
+ end
166
+
167
+ def serializable_hash
168
+ @object.as_json(@options)
169
+ end
170
+ end
171
+ end
172
+ end
173
+ end
174
+ ```
175
+ Add this class to your app however you see fit. This is the class that existing uses of
176
+ `ActiveModel::ArraySerializer` should be changed to use.
177
+
178
+ ### 4. Add `ActiveModelSerializers::Adapter::V08Adapter`
179
+ ```ruby
180
+ module ActiveModelSerializers
181
+ module Adapter
182
+ class V08Adapter < ActiveModelSerializers::Adapter::Base
183
+ def serializable_hash(options = nil)
184
+ options ||= {}
185
+
186
+ if serializer.respond_to?(:each)
187
+ if serializer.root
188
+ delegate_to_json_adapter(options)
189
+ else
190
+ serializable_hash_for_collection(options)
191
+ end
192
+ else
193
+ serializable_hash_for_single_resource(options)
194
+ end
195
+ end
196
+
197
+ def serializable_hash_for_collection(options)
198
+ serializer.map do |s|
199
+ V08Adapter.new(s, instance_options)
200
+ .serializable_hash(options)
201
+ end
202
+ end
203
+
204
+ def serializable_hash_for_single_resource(options)
205
+ if serializer.object.is_a?(ActiveModel::Serializer)
206
+ # It is recommended that you add some logging here to indicate
207
+ # places that should get converted to eventually allow for this
208
+ # adapter to get removed.
209
+ @serializer = serializer.object
210
+ end
211
+
212
+ if serializer.root
213
+ delegate_to_json_adapter(options)
214
+ else
215
+ options = serialization_options(options)
216
+ serializer.serializable_hash(instance_options, options, self)
217
+ end
218
+ end
219
+
220
+ def delegate_to_json_adapter(options)
221
+ ActiveModelSerializers::Adapter::Json
222
+ .new(serializer, instance_options)
223
+ .serializable_hash(options)
224
+ end
225
+ end
226
+ end
227
+ end
228
+ ```
229
+ Add this class to your app however you see fit.
230
+
231
+ Add
232
+ ```ruby
233
+ ActiveModelSerializers.config.adapter =
234
+ ActiveModelSerializers::Adapter::V08Adapter
235
+ ```
236
+ to `config/active_model_serializer.rb` to configure AMS to use this
237
+ class as the default adapter.
238
+
239
+ ### 5. Change inheritors of `ActiveModel::Serializer` to inherit from `ActiveModel::V08::Serializer`
240
+ Simple find/replace
241
+
242
+ ### 6. Remove `private` keyword from serializers
243
+ Simple find/replace. This is required to allow the `ActiveModel::V08::Serializer`
244
+ to have proper access to the methods defined in the serializer.
245
+
246
+ You may be able to change the `private` to `protected`, but this is hasn't been tested yet.
247
+
248
+ ### 7. Remove references to `ActiveRecord::Base#active_model_serializer`
249
+ This method is no longer supported in `0.10`.
250
+
251
+ `0.10` does a good job of discovering serializers for `ActiveRecord` objects.
252
+
253
+ ### 8. Rename `ActiveModel::ArraySerializer` to `ActiveModel::V08::CollectionSerializer`
254
+ Find/replace uses of `ActiveModel::ArraySerializer` with `ActiveModel::V08::CollectionSerializer`.
255
+
256
+ Also, be sure to change the `each_serializer` keyword to `serializer` when calling making the replacement.
257
+
258
+ ### 9. Replace uses of `@options` to `instance_options` in serializers
259
+ Simple find/replace
260
+
261
+ ## Conclusion
262
+ After you've done the steps above, you should test your app to ensure that everything is still working properly.
263
+
264
+ If you run into issues, please contribute back to this document so others can benefit from your knowledge.
265
+