active_model_serializers 0.10.9 → 0.10.13

Sign up to get free protection for your applications and to get access to all the features.
Files changed (161) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +41 -2
  3. data/README.md +18 -19
  4. data/lib/action_controller/serialization.rb +9 -1
  5. data/lib/active_model/serializer/collection_serializer.rb +11 -2
  6. data/lib/active_model/serializer/concerns/caching.rb +2 -1
  7. data/lib/active_model/serializer/fieldset.rb +1 -1
  8. data/lib/active_model/serializer/reflection.rb +4 -4
  9. data/lib/active_model/serializer/version.rb +1 -1
  10. data/lib/active_model/serializer.rb +13 -4
  11. data/lib/active_model_serializers/adapter/attributes.rb +21 -0
  12. data/lib/active_model_serializers/adapter/json_api/pagination_links.rb +5 -1
  13. data/lib/active_model_serializers/adapter/json_api/resource_identifier.rb +1 -1
  14. data/lib/active_model_serializers/model/caching.rb +26 -0
  15. metadata +20 -292
  16. data/.github/ISSUE_TEMPLATE.md +0 -29
  17. data/.github/PULL_REQUEST_TEMPLATE.md +0 -15
  18. data/.gitignore +0 -35
  19. data/.rubocop.yml +0 -109
  20. data/.simplecov +0 -110
  21. data/.travis.yml +0 -63
  22. data/CODE_OF_CONDUCT.md +0 -74
  23. data/CONTRIBUTING.md +0 -105
  24. data/Gemfile +0 -74
  25. data/Rakefile +0 -76
  26. data/active_model_serializers.gemspec +0 -64
  27. data/appveyor.yml +0 -28
  28. data/bin/bench +0 -171
  29. data/bin/bench_regression +0 -316
  30. data/bin/rubocop +0 -38
  31. data/bin/serve_benchmark +0 -39
  32. data/docs/README.md +0 -41
  33. data/docs/STYLE.md +0 -58
  34. data/docs/general/adapters.md +0 -269
  35. data/docs/general/caching.md +0 -58
  36. data/docs/general/configuration_options.md +0 -185
  37. data/docs/general/deserialization.md +0 -100
  38. data/docs/general/fields.md +0 -31
  39. data/docs/general/getting_started.md +0 -133
  40. data/docs/general/instrumentation.md +0 -40
  41. data/docs/general/key_transforms.md +0 -40
  42. data/docs/general/logging.md +0 -21
  43. data/docs/general/rendering.md +0 -293
  44. data/docs/general/serializers.md +0 -495
  45. data/docs/how-open-source-maintained.jpg +0 -0
  46. data/docs/howto/add_pagination_links.md +0 -138
  47. data/docs/howto/add_relationship_links.md +0 -140
  48. data/docs/howto/add_root_key.md +0 -62
  49. data/docs/howto/grape_integration.md +0 -42
  50. data/docs/howto/outside_controller_use.md +0 -66
  51. data/docs/howto/passing_arbitrary_options.md +0 -27
  52. data/docs/howto/serialize_poro.md +0 -73
  53. data/docs/howto/test.md +0 -154
  54. data/docs/howto/upgrade_from_0_8_to_0_10.md +0 -265
  55. data/docs/integrations/ember-and-json-api.md +0 -147
  56. data/docs/integrations/grape.md +0 -19
  57. data/docs/jsonapi/errors.md +0 -56
  58. data/docs/jsonapi/schema/schema.json +0 -366
  59. data/docs/jsonapi/schema.md +0 -151
  60. data/docs/rfcs/0000-namespace.md +0 -106
  61. data/docs/rfcs/template.md +0 -15
  62. data/test/action_controller/adapter_selector_test.rb +0 -64
  63. data/test/action_controller/explicit_serializer_test.rb +0 -137
  64. data/test/action_controller/json/include_test.rb +0 -248
  65. data/test/action_controller/json_api/deserialization_test.rb +0 -114
  66. data/test/action_controller/json_api/errors_test.rb +0 -42
  67. data/test/action_controller/json_api/fields_test.rb +0 -68
  68. data/test/action_controller/json_api/linked_test.rb +0 -204
  69. data/test/action_controller/json_api/pagination_test.rb +0 -126
  70. data/test/action_controller/json_api/transform_test.rb +0 -191
  71. data/test/action_controller/lookup_proc_test.rb +0 -51
  72. data/test/action_controller/namespace_lookup_test.rb +0 -234
  73. data/test/action_controller/serialization_scope_name_test.rb +0 -237
  74. data/test/action_controller/serialization_test.rb +0 -480
  75. data/test/active_model_serializers/adapter_for_test.rb +0 -210
  76. data/test/active_model_serializers/json_pointer_test.rb +0 -24
  77. data/test/active_model_serializers/logging_test.rb +0 -79
  78. data/test/active_model_serializers/model_test.rb +0 -144
  79. data/test/active_model_serializers/railtie_test_isolated.rb +0 -70
  80. data/test/active_model_serializers/register_jsonapi_renderer_test_isolated.rb +0 -163
  81. data/test/active_model_serializers/serialization_context_test_isolated.rb +0 -73
  82. data/test/active_model_serializers/test/schema_test.rb +0 -133
  83. data/test/active_model_serializers/test/serializer_test.rb +0 -64
  84. data/test/active_record_test.rb +0 -11
  85. data/test/adapter/attributes_test.rb +0 -42
  86. data/test/adapter/deprecation_test.rb +0 -102
  87. data/test/adapter/json/belongs_to_test.rb +0 -47
  88. data/test/adapter/json/collection_test.rb +0 -106
  89. data/test/adapter/json/has_many_test.rb +0 -55
  90. data/test/adapter/json/transform_test.rb +0 -95
  91. data/test/adapter/json_api/belongs_to_test.rb +0 -157
  92. data/test/adapter/json_api/collection_test.rb +0 -98
  93. data/test/adapter/json_api/errors_test.rb +0 -78
  94. data/test/adapter/json_api/fields_test.rb +0 -98
  95. data/test/adapter/json_api/has_many_explicit_serializer_test.rb +0 -98
  96. data/test/adapter/json_api/has_many_test.rb +0 -175
  97. data/test/adapter/json_api/has_one_test.rb +0 -82
  98. data/test/adapter/json_api/include_data_if_sideloaded_test.rb +0 -215
  99. data/test/adapter/json_api/json_api_test.rb +0 -35
  100. data/test/adapter/json_api/linked_test.rb +0 -415
  101. data/test/adapter/json_api/links_test.rb +0 -112
  102. data/test/adapter/json_api/pagination_links_test.rb +0 -208
  103. data/test/adapter/json_api/parse_test.rb +0 -139
  104. data/test/adapter/json_api/relationship_test.rb +0 -399
  105. data/test/adapter/json_api/resource_meta_test.rb +0 -102
  106. data/test/adapter/json_api/toplevel_jsonapi_test.rb +0 -84
  107. data/test/adapter/json_api/transform_test.rb +0 -514
  108. data/test/adapter/json_api/type_test.rb +0 -195
  109. data/test/adapter/json_test.rb +0 -48
  110. data/test/adapter/null_test.rb +0 -24
  111. data/test/adapter/polymorphic_test.rb +0 -220
  112. data/test/adapter_test.rb +0 -69
  113. data/test/array_serializer_test.rb +0 -24
  114. data/test/benchmark/app.rb +0 -67
  115. data/test/benchmark/benchmarking_support.rb +0 -69
  116. data/test/benchmark/bm_active_record.rb +0 -83
  117. data/test/benchmark/bm_adapter.rb +0 -40
  118. data/test/benchmark/bm_caching.rb +0 -121
  119. data/test/benchmark/bm_lookup_chain.rb +0 -85
  120. data/test/benchmark/bm_transform.rb +0 -47
  121. data/test/benchmark/config.ru +0 -3
  122. data/test/benchmark/controllers.rb +0 -85
  123. data/test/benchmark/fixtures.rb +0 -221
  124. data/test/cache_test.rb +0 -717
  125. data/test/collection_serializer_test.rb +0 -129
  126. data/test/fixtures/active_record.rb +0 -115
  127. data/test/fixtures/poro.rb +0 -227
  128. data/test/generators/scaffold_controller_generator_test.rb +0 -26
  129. data/test/generators/serializer_generator_test.rb +0 -77
  130. data/test/grape_test.rb +0 -198
  131. data/test/lint_test.rb +0 -51
  132. data/test/logger_test.rb +0 -22
  133. data/test/poro_test.rb +0 -11
  134. data/test/serializable_resource_test.rb +0 -81
  135. data/test/serializers/association_macros_test.rb +0 -39
  136. data/test/serializers/associations_test.rb +0 -520
  137. data/test/serializers/attribute_test.rb +0 -155
  138. data/test/serializers/attributes_test.rb +0 -54
  139. data/test/serializers/caching_configuration_test_isolated.rb +0 -172
  140. data/test/serializers/configuration_test.rb +0 -34
  141. data/test/serializers/fieldset_test.rb +0 -16
  142. data/test/serializers/meta_test.rb +0 -204
  143. data/test/serializers/options_test.rb +0 -34
  144. data/test/serializers/read_attribute_for_serialization_test.rb +0 -81
  145. data/test/serializers/reflection_test.rb +0 -481
  146. data/test/serializers/root_test.rb +0 -23
  147. data/test/serializers/serialization_test.rb +0 -57
  148. data/test/serializers/serializer_for_test.rb +0 -138
  149. data/test/serializers/serializer_for_with_namespace_test.rb +0 -90
  150. data/test/support/custom_schemas/active_model_serializers/test/schema_test/my/index.json +0 -6
  151. data/test/support/isolated_unit.rb +0 -86
  152. data/test/support/rails5_shims.rb +0 -55
  153. data/test/support/rails_app.rb +0 -40
  154. data/test/support/schemas/active_model_serializers/test/schema_test/my/index.json +0 -6
  155. data/test/support/schemas/active_model_serializers/test/schema_test/my/show.json +0 -6
  156. data/test/support/schemas/custom/show.json +0 -7
  157. data/test/support/schemas/hyper_schema.json +0 -93
  158. data/test/support/schemas/render_using_json_api.json +0 -43
  159. data/test/support/schemas/simple_json_pointers.json +0 -10
  160. data/test/support/serialization_testing.rb +0 -81
  161. data/test/test_helper.rb +0 -72
@@ -1,495 +0,0 @@
1
- [Back to Guides](../README.md)
2
-
3
- # Serializers
4
-
5
- Given a serializer class:
6
-
7
- ```ruby
8
- class SomeSerializer < ActiveModel::Serializer
9
- end
10
- ```
11
-
12
- The following methods may be defined in it:
13
-
14
- ### Attributes
15
-
16
- #### ::attributes
17
-
18
- Serialization of the resource `title` and `body`
19
-
20
- | In Serializer | #attributes |
21
- |---------------------------- |-------------|
22
- | `attributes :title, :body` | `{ title: 'Some Title', body: 'Some Body' }`
23
- | `attributes :title, :body`<br>`def body "Special #{object.body}" end` | `{ title: 'Some Title', body: 'Special Some Body' }`
24
-
25
-
26
- #### ::attribute
27
-
28
- Serialization of the resource `title`
29
-
30
- | In Serializer | #attributes |
31
- |---------------------------- |-------------|
32
- | `attribute :title` | `{ title: 'Some Title' } `
33
- | `attribute :title, key: :name` | `{ name: 'Some Title' } `
34
- | `attribute(:title) { 'A Different Title'}` | `{ title: 'A Different Title' } `
35
- | `attribute :title`<br>`def title 'A Different Title' end` | `{ title: 'A Different Title' }`
36
-
37
- An `if` or `unless` option can make an attribute conditional. It takes a symbol of a method name on the serializer, or a lambda literal.
38
-
39
- e.g.
40
-
41
- ```ruby
42
- attribute :private_data, if: :is_current_user?
43
- attribute :another_private_data, if: -> { scope.admin? }
44
-
45
- def is_current_user?
46
- object.id == current_user.id
47
- end
48
- ```
49
-
50
- ### Associations
51
-
52
- The interface for associations is, generically:
53
-
54
- > `association_type(association_name, options, &block)`
55
-
56
- Where:
57
-
58
- - `association_type` may be `has_one`, `has_many`, `belongs_to`.
59
- - `association_name` is a method name the serializer calls.
60
- - optional: `options` may be:
61
- - `key:` The name used for the serialized association.
62
- - `serializer:`
63
- - `if:`
64
- - `unless:`
65
- - `virtual_value:`
66
- - `polymorphic:` defines if polymorphic relation type should be nested in serialized association.
67
- - `type:` the resource type as used by JSON:API, especially on a `belongs_to` relationship.
68
- - `class_name:` the (String) model name used to determine `type`, when `type` is not given. e.g. `class_name: "Comment"` would imply the type `comments`
69
- - `foreign_key:` used by JSON:API on a `belongs_to` relationship to avoid unnecessarily loading the association object.
70
- - `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.
71
- - optional: `&block` is a context that returns the association's attributes.
72
- - prevents `association_name` method from being called.
73
- - return value of block is used as the association value.
74
- - yields the `serializer` to the block.
75
- - `include_data false` prevents the `data` key from being rendered in the JSON API relationship.
76
-
77
- #### ::has_one
78
-
79
- e.g.
80
-
81
- ```ruby
82
- has_one :bio
83
- has_one :blog, key: :site
84
- has_one :blog, class_name: "Blog"
85
- has_one :maker, virtual_value: { id: 1 }
86
-
87
- has_one :blog do |serializer|
88
- serializer.cached_blog
89
- end
90
-
91
- def cached_blog
92
- cache_store.fetch("cached_blog:#{object.updated_at}") do
93
- Blog.find(object.blog_id)
94
- end
95
- end
96
- ```
97
-
98
- ```ruby
99
- has_one :blog, if: :show_blog?
100
- # you can also use a string or lambda
101
- # has_one :blog, if: 'scope.admin?'
102
- # has_one :blog, if: -> (serializer) { serializer.scope.admin? }
103
- # has_one :blog, if: -> { scope.admin? }
104
-
105
- def show_blog?
106
- scope.admin?
107
- end
108
- ```
109
-
110
- #### ::has_many
111
-
112
- e.g.
113
-
114
- ```ruby
115
- has_many :comments
116
- has_many :comments, key: :reviews
117
- has_many :comments, serializer: CommentPreviewSerializer
118
- has_many :comments, class_name: "Comment"
119
- has_many :reviews, virtual_value: [{ id: 1 }, { id: 2 }]
120
- has_many :comments, key: :last_comments do
121
- last(1)
122
- end
123
- ```
124
-
125
- #### ::belongs_to
126
-
127
- e.g.
128
-
129
- ```ruby
130
- belongs_to :author, serializer: AuthorPreviewSerializer
131
- belongs_to :author, key: :writer
132
- belongs_to :author, class_name: "Author"
133
- belongs_to :post
134
- belongs_to :blog
135
- def blog
136
- Blog.new(id: 999, name: 'Custom blog')
137
- end
138
- ```
139
-
140
- ### Polymorphic Relationships
141
-
142
- Polymorphic relationships are serialized by specifying the relationship, like any other association. For example:
143
-
144
- ```ruby
145
- class PictureSerializer < ActiveModel::Serializer
146
- has_one :imageable
147
- end
148
- ```
149
-
150
- You can specify the serializers by [overriding serializer_for](serializers.md#overriding-association-serializer-lookup). For more context about polymorphic relationships, see the [tests](../../test/adapter/polymorphic_test.rb) for each adapter.
151
-
152
- ### Caching
153
-
154
- #### ::cache
155
-
156
- e.g.
157
-
158
- ```ruby
159
- cache key: 'post', expires_in: 0.1, skip_digest: true
160
- cache expires_in: 1.day, skip_digest: true
161
- cache key: 'writer', skip_digest: true
162
- cache only: [:name], skip_digest: true
163
- cache except: [:content], skip_digest: true
164
- cache key: 'blog'
165
- cache only: [:id]
166
- ```
167
-
168
- #### #cache_key
169
-
170
- e.g.
171
-
172
- ```ruby
173
- # Uses a custom non-time-based cache key
174
- def cache_key
175
- "#{self.class.name.downcase}/#{self.id}"
176
- end
177
- ```
178
-
179
- ### Other
180
-
181
- #### ::type
182
-
183
- When using the `:json_api` adapter, the `::type` method defines the JSONAPI [type](http://jsonapi.org/format/#document-resource-object-identification) that will be rendered for this serializer.
184
-
185
- When using the `:json` adapter, the `::type` method defines the name of the root element.
186
-
187
- It either takes a `String` or `Symbol` as parameter.
188
-
189
- Note: This method is useful only when using the `:json_api` or `:json` adapter.
190
-
191
- Examples:
192
- ```ruby
193
- class UserProfileSerializer < ActiveModel::Serializer
194
- type 'profile'
195
-
196
- attribute :name
197
- end
198
- class AuthorProfileSerializer < ActiveModel::Serializer
199
- type :profile
200
-
201
- attribute :name
202
- end
203
- ```
204
-
205
- With the `:json_api` adapter, the previous serializers would be rendered as:
206
-
207
- ``` json
208
- {
209
- "data": {
210
- "id": "1",
211
- "type": "profile",
212
- "attributes": {
213
- "name": "Julia"
214
- }
215
- }
216
- }
217
- ```
218
-
219
- With the `:json` adapter, the previous serializer would be rendered as:
220
-
221
- ``` json
222
- {
223
- "profile": {
224
- "name": "Julia"
225
- }
226
- }
227
- ```
228
-
229
- #### ::link
230
-
231
- ```ruby
232
- link :self do
233
- href "https://example.com/link_author/#{object.id}"
234
- end
235
- link(:author) { link_author_url(object) }
236
- link(:link_authors) { link_authors_url }
237
- link :other, 'https://example.com/resource'
238
- link(:posts) { link_author_posts_url(object) }
239
- ```
240
-
241
- Just like attributes, links also support conditions in options
242
- ```ruby
243
- link(:secret, if: :internal?) { object.secret_link }
244
-
245
- def internal?
246
- instance_options[:context] == :internal
247
- end
248
- ```
249
-
250
- #### #object
251
-
252
- The object being serialized.
253
-
254
- #### #root
255
-
256
- Resource root which is included in `JSON` adapter. As you can see at [Adapters Document](adapters.md), `Attribute` adapter (default) and `JSON API` adapter does not include root at top level.
257
- By default, the resource root comes from the `model_name` of the serialized object's class.
258
-
259
- There are several ways to specify root:
260
- * [Overriding the root key](rendering.md#overriding-the-root-key)
261
- * [Setting `type`](serializers.md#type)
262
- * Specifying the `root` option, e.g. `root: 'specific_name'`, during the serializer's initialization:
263
-
264
- ```ruby
265
- ActiveModelSerializers::SerializableResource.new(foo, root: 'bar')
266
- ```
267
-
268
- #### #scope
269
-
270
- Allows you to include in the serializer access to an external method.
271
-
272
- It's intended to provide an authorization context to the serializer, so that
273
- you may e.g. show an admin all comments on a post, else only published comments.
274
-
275
- - `scope` is a method on the serializer instance that comes from `options[:scope]`. It may be nil.
276
- - `scope_name` is an option passed to the new serializer (`options[:scope_name]`). The serializer
277
- defines a method with that name that calls the `scope`, e.g. `def current_user; scope; end`.
278
- Note: it does not define the method if the serializer instance responds to it.
279
-
280
- That's a lot of words, so here's some examples:
281
-
282
- First, let's assume the serializer is instantiated in the controller, since that's the usual scenario.
283
- We'll refer to the serialization context as `controller`.
284
-
285
- | options | `Serializer#scope` | method definition |
286
- |-------- | ------------------|--------------------|
287
- | `scope: current_user, scope_name: :current_user` | `current_user` | `Serializer#current_user` calls `controller.current_user`
288
- | `scope: view_context, scope_name: :view_context` | `view_context` | `Serializer#view_context` calls `controller.view_context`
289
-
290
- We can take advantage of the scope to customize the objects returned based
291
- on the current user (scope).
292
-
293
- For example, we can limit the posts the current user sees to those they created:
294
-
295
- ```ruby
296
- class PostSerializer < ActiveModel::Serializer
297
- attributes :id, :title, :body
298
-
299
- # scope comments to those created_by the current user
300
- has_many :comments do
301
- object.comments.where(created_by: current_user)
302
- end
303
- end
304
- ```
305
-
306
- Whether you write the method as above or as `object.comments.where(created_by: scope)`
307
- is a matter of preference (assuming `scope_name` has been set).
308
-
309
- Keep in mind that the scope can be set to any available controller reference. This can be utilized to provide access to any other data scopes or presentation helpers.
310
-
311
- ##### Controller Authorization Context
312
-
313
- In the controller, the scope/scope_name options are equal to
314
- the [`serialization_scope`method](https://github.com/rails-api/active_model_serializers/blob/d02cd30fe55a3ea85e1d351b6e039620903c1871/lib/action_controller/serialization.rb#L13-L20),
315
- which is `:current_user`, by default.
316
-
317
- Specifically, the `scope_name` is defaulted to `:current_user`, and may be set as
318
- `serialization_scope :view_context`. The `scope` is set to `send(scope_name)` when `scope_name` is
319
- present and the controller responds to `scope_name`.
320
-
321
- Thus, in a serializer, the controller provides `current_user` as the
322
- current authorization scope when you call `render :json`.
323
-
324
- **IMPORTANT**: Since the scope is set at render, you may want to customize it so that `current_user` isn't
325
- called on every request. This was [also a problem](https://github.com/rails-api/active_model_serializers/pull/1252#issuecomment-159810477)
326
- in [`0.9`](https://github.com/rails-api/active_model_serializers/tree/0-9-stable#customizing-scope).
327
-
328
- We can change the scope from `current_user` to `view_context`, which is included in subclasses of `ActionController::Base`.
329
-
330
- ```diff
331
- class SomeController < ActionController::Base
332
- + serialization_scope :view_context
333
-
334
- def current_user
335
- User.new(id: 2, name: 'Bob', admin: true)
336
- end
337
-
338
- def edit
339
- user = User.new(id: 1, name: 'Pete')
340
- render json: user, serializer: AdminUserSerializer, adapter: :json_api
341
- end
342
- end
343
- ```
344
-
345
- We could then use the controller method `view_context` in our serializer, like so:
346
-
347
- ```diff
348
- class AdminUserSerializer < ActiveModel::Serializer
349
- attributes :id, :name, :can_edit
350
-
351
- def can_edit?
352
- + view_context.current_user.admin?
353
- end
354
- end
355
- ```
356
-
357
- So that when we render the `#edit` action, we'll get
358
-
359
- ```json
360
- {"data":{"id":"1","type":"users","attributes":{"name":"Pete","can_edit":true}}}
361
- ```
362
-
363
- Where `can_edit` is `view_context.current_user.admin?` (true).
364
-
365
- You can also tell what to set as `serialization_scope` for specific actions.
366
-
367
- For example, use `admin_user` only for `Admin::PostSerializer` and `current_user` for rest.
368
-
369
- ```ruby
370
- class PostsController < ActionController::Base
371
-
372
- before_action only: :edit do
373
- self.class.serialization_scope :admin_user
374
- end
375
-
376
- def show
377
- render json: @post, serializer: PostSerializer
378
- end
379
-
380
- def edit
381
- @post.save
382
- render json: @post, serializer: Admin::PostSerializer
383
- end
384
-
385
- private
386
-
387
- def admin_user
388
- User.new(id: 2, name: 'Bob', admin: true)
389
- end
390
-
391
- def current_user
392
- User.new(id: 2, name: 'Bob', admin: false)
393
- end
394
- end
395
- ```
396
- Note that any controller reference which provides the desired scope is acceptable, such as another controller method for loading a different resource or reference to helpers. For example, `ActionController::API` does not include `ActionView::ViewContext`, and would need a different reference for passing any helpers into a serializer via `serialization_scope`.
397
-
398
- #### #read_attribute_for_serialization(key)
399
-
400
- The serialized value for a given key. e.g. `read_attribute_for_serialization(:title) #=> 'Hello World'`
401
-
402
- #### #links
403
-
404
- 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.
405
-
406
- ```ruby
407
- ActiveModelSerializers::SerializableResource.new(
408
- @post,
409
- adapter: :json_api,
410
- links: {
411
- self: {
412
- href: 'http://example.com/posts',
413
- meta: {
414
- stuff: 'value'
415
- }
416
- }
417
- }
418
- )
419
- ```
420
-
421
- #### #json_key
422
-
423
- Returns the key used by the adapter as the resource root. See [root](#root) for more information.
424
-
425
- ## Examples
426
-
427
- Given two models, a `Post(title: string, body: text)` and a
428
- `Comment(name: string, body: text, post_id: integer)`, you will have two
429
- serializers:
430
-
431
- ```ruby
432
- class PostSerializer < ActiveModel::Serializer
433
- cache key: 'posts', expires_in: 3.hours
434
- attributes :title, :body
435
-
436
- has_many :comments
437
- end
438
- ```
439
-
440
- and
441
-
442
- ```ruby
443
- class CommentSerializer < ActiveModel::Serializer
444
- attributes :name, :body
445
-
446
- belongs_to :post
447
- end
448
- ```
449
-
450
- Generally speaking, you, as a user of ActiveModelSerializers, will write (or generate) these
451
- serializer classes.
452
-
453
- ## More Info
454
-
455
- For more information, see [the Serializer class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer.rb)
456
-
457
- ## Overriding association methods
458
-
459
- To override an association, call `has_many`, `has_one` or `belongs_to` with a block:
460
-
461
- ```ruby
462
- class PostSerializer < ActiveModel::Serializer
463
- has_many :comments do
464
- object.comments.active
465
- end
466
- end
467
- ```
468
-
469
- ## Overriding attribute methods
470
-
471
- To override an attribute, call `attribute` with a block:
472
-
473
- ```ruby
474
- class PostSerializer < ActiveModel::Serializer
475
- attribute :body do
476
- object.body.downcase
477
- end
478
- end
479
- ```
480
-
481
- ## Overriding association serializer lookup
482
-
483
- If you want to define a specific serializer lookup for your associations, you can override
484
- the `ActiveModel::Serializer.serializer_for` method to return a serializer class based on defined conditions.
485
-
486
- ```ruby
487
- class MySerializer < ActiveModel::Serializer
488
- def self.serializer_for(model, options)
489
- return SparseAdminSerializer if model.class.name == 'Admin'
490
- super
491
- end
492
-
493
- # the rest of the serializer
494
- end
495
- ```
Binary file
@@ -1,138 +0,0 @@
1
- [Back to Guides](../README.md)
2
-
3
- # How to add pagination links
4
-
5
- ### JSON API adapter
6
-
7
- Pagination links will be included in your response automatically as long as
8
- the resource is paginated and if you are using the ```JsonApi``` adapter.
9
-
10
- If you want pagination links in your response, use [Kaminari](https://github.com/amatsuda/kaminari)
11
- or [WillPaginate](https://github.com/mislav/will_paginate).
12
-
13
- Although the other adapters do not have this feature, it is possible to
14
- implement pagination links to `JSON` adapter. For more information about it,
15
- please check our docs.
16
-
17
- ###### Kaminari examples
18
-
19
- ```ruby
20
- #array
21
- @posts = Kaminari.paginate_array([1, 2, 3]).page(3).per(1)
22
- render json: @posts
23
-
24
- #active_record
25
- @posts = Post.page(3).per(1)
26
- render json: @posts
27
- ```
28
-
29
- ###### WillPaginate examples
30
-
31
- ```ruby
32
- #array
33
- @posts = [1,2,3].paginate(page: 3, per_page: 1)
34
- render json: @posts
35
-
36
- #active_record
37
- @posts = Post.page(3).per_page(1)
38
- render json: @posts
39
- ```
40
-
41
- ```ruby
42
- ActiveModelSerializers.config.adapter = :json_api
43
- ```
44
-
45
- ex:
46
- ```json
47
- {
48
- "data": [
49
- {
50
- "type": "articles",
51
- "id": "3",
52
- "attributes": {
53
- "title": "JSON API paints my bikeshed!",
54
- "body": "The shortest article. Ever.",
55
- "created": "2015-05-22T14:56:29.000Z",
56
- "updated": "2015-05-22T14:56:28.000Z"
57
- }
58
- }
59
- ],
60
- "links": {
61
- "self": "http://example.com/articles?page[number]=3&page[size]=1",
62
- "first": "http://example.com/articles?page[number]=1&page[size]=1",
63
- "prev": "http://example.com/articles?page[number]=2&page[size]=1",
64
- "next": "http://example.com/articles?page[number]=4&page[size]=1",
65
- "last": "http://example.com/articles?page[number]=13&page[size]=1"
66
- }
67
- }
68
- ```
69
-
70
- ActiveModelSerializers pagination relies on a paginated collection with the methods `current_page`, `total_pages`, and `size`, such as are supported by both [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
71
-
72
-
73
- ### JSON adapter
74
-
75
- If you are not using `JSON` adapter, pagination links will not be included automatically, but it is possible to do so using `meta` key.
76
-
77
- Add this method to your base API controller.
78
-
79
- ```ruby
80
- def pagination_dict(collection)
81
- {
82
- current_page: collection.current_page,
83
- next_page: collection.next_page,
84
- prev_page: collection.prev_page, # use collection.previous_page when using will_paginate
85
- total_pages: collection.total_pages,
86
- total_count: collection.total_count
87
- }
88
- end
89
- ```
90
-
91
- Then, use it on your render method.
92
-
93
- ```ruby
94
- render json: posts, meta: pagination_dict(posts)
95
- ```
96
-
97
- ex.
98
- ```json
99
- {
100
- "posts": [
101
- {
102
- "id": 2,
103
- "title": "JSON API paints my bikeshed!",
104
- "body": "The shortest article. Ever."
105
- }
106
- ],
107
- "meta": {
108
- "current_page": 3,
109
- "next_page": 4,
110
- "prev_page": 2,
111
- "total_pages": 10,
112
- "total_count": 10
113
- }
114
- }
115
- ```
116
-
117
- You can also achieve the same result if you have a helper method that adds the pagination info in the meta tag. For instance, in your action specify a custom serializer.
118
-
119
- ```ruby
120
- render json: @posts, each_serializer: PostPreviewSerializer, meta: meta_attributes(@posts)
121
- ```
122
-
123
- ```ruby
124
- #expects pagination!
125
- def meta_attributes(collection, extra_meta = {})
126
- {
127
- current_page: collection.current_page,
128
- next_page: collection.next_page,
129
- prev_page: collection.prev_page, # use collection.previous_page when using will_paginate
130
- total_pages: collection.total_pages,
131
- total_count: collection.total_count
132
- }.merge(extra_meta)
133
- end
134
- ```
135
-
136
- ### Attributes adapter
137
-
138
- This adapter does not allow us to use `meta` key, due to that it is not possible to add pagination links.