active_model_serializers 0.8.3 → 0.10.0.rc4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (184) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +6 -0
  3. data/.rubocop.yml +86 -0
  4. data/.rubocop_todo.yml +240 -0
  5. data/.simplecov +111 -0
  6. data/.travis.yml +33 -22
  7. data/CHANGELOG.md +358 -6
  8. data/CONTRIBUTING.md +220 -0
  9. data/Gemfile +46 -1
  10. data/{MIT-LICENSE.txt → LICENSE.txt} +3 -2
  11. data/README.md +81 -591
  12. data/Rakefile +68 -11
  13. data/active_model_serializers.gemspec +57 -23
  14. data/appveyor.yml +27 -0
  15. data/docs/ARCHITECTURE.md +120 -0
  16. data/docs/DESIGN.textile +8 -0
  17. data/docs/README.md +35 -0
  18. data/docs/general/adapters.md +162 -0
  19. data/docs/general/caching.md +52 -0
  20. data/docs/general/configuration_options.md +27 -0
  21. data/docs/general/getting_started.md +98 -0
  22. data/docs/general/instrumentation.md +40 -0
  23. data/docs/general/logging.md +14 -0
  24. data/docs/general/rendering.md +153 -0
  25. data/docs/general/serializers.md +207 -0
  26. data/docs/how-open-source-maintained.jpg +0 -0
  27. data/docs/howto/add_pagination_links.md +121 -0
  28. data/docs/howto/add_root_key.md +51 -0
  29. data/docs/howto/outside_controller_use.md +58 -0
  30. data/docs/howto/test.md +152 -0
  31. data/docs/integrations/ember-and-json-api.md +112 -0
  32. data/docs/integrations/grape.md +19 -0
  33. data/docs/jsonapi/schema/schema.json +366 -0
  34. data/docs/jsonapi/schema.md +140 -0
  35. data/lib/action_controller/serialization.rb +41 -37
  36. data/lib/active_model/serializable_resource.rb +72 -0
  37. data/lib/active_model/serializer/adapter/attributes.rb +66 -0
  38. data/lib/active_model/serializer/adapter/base.rb +58 -0
  39. data/lib/active_model/serializer/adapter/cached_serializer.rb +45 -0
  40. data/lib/active_model/serializer/adapter/fragment_cache.rb +111 -0
  41. data/lib/active_model/serializer/adapter/json/fragment_cache.rb +13 -0
  42. data/lib/active_model/serializer/adapter/json.rb +21 -0
  43. data/lib/active_model/serializer/adapter/json_api/deserialization.rb +207 -0
  44. data/lib/active_model/serializer/adapter/json_api/fragment_cache.rb +21 -0
  45. data/lib/active_model/serializer/adapter/json_api/link.rb +44 -0
  46. data/lib/active_model/serializer/adapter/json_api/pagination_links.rb +58 -0
  47. data/lib/active_model/serializer/adapter/json_api.rb +223 -0
  48. data/lib/active_model/serializer/adapter/null.rb +11 -0
  49. data/lib/active_model/serializer/adapter.rb +91 -0
  50. data/lib/active_model/serializer/array_serializer.rb +9 -0
  51. data/lib/active_model/serializer/association.rb +20 -0
  52. data/lib/active_model/serializer/associations.rb +87 -220
  53. data/lib/active_model/serializer/attribute.rb +25 -0
  54. data/lib/active_model/serializer/attributes.rb +82 -0
  55. data/lib/active_model/serializer/belongs_to_reflection.rb +10 -0
  56. data/lib/active_model/serializer/caching.rb +100 -0
  57. data/lib/active_model/serializer/collection_reflection.rb +7 -0
  58. data/lib/active_model/serializer/collection_serializer.rb +47 -0
  59. data/lib/active_model/serializer/configuration.rb +28 -0
  60. data/lib/active_model/serializer/field.rb +56 -0
  61. data/lib/active_model/serializer/fieldset.rb +31 -0
  62. data/lib/active_model/serializer/has_many_reflection.rb +10 -0
  63. data/lib/active_model/serializer/has_one_reflection.rb +10 -0
  64. data/lib/active_model/serializer/include_tree.rb +111 -0
  65. data/lib/active_model/serializer/links.rb +33 -0
  66. data/lib/active_model/serializer/lint.rb +142 -0
  67. data/lib/active_model/serializer/reflection.rb +91 -0
  68. data/lib/active_model/serializer/singular_reflection.rb +7 -0
  69. data/lib/active_model/serializer/type.rb +25 -0
  70. data/lib/active_model/{serializers → serializer}/version.rb +1 -1
  71. data/lib/active_model/serializer.rb +99 -479
  72. data/lib/active_model_serializers/callbacks.rb +55 -0
  73. data/lib/active_model_serializers/deserialization.rb +13 -0
  74. data/lib/active_model_serializers/logging.rb +119 -0
  75. data/lib/active_model_serializers/model.rb +39 -0
  76. data/lib/active_model_serializers/railtie.rb +38 -0
  77. data/lib/active_model_serializers/serialization_context.rb +10 -0
  78. data/lib/active_model_serializers/test/schema.rb +103 -0
  79. data/lib/active_model_serializers/test/serializer.rb +125 -0
  80. data/lib/active_model_serializers/test.rb +7 -0
  81. data/lib/active_model_serializers.rb +20 -92
  82. data/lib/generators/rails/USAGE +6 -0
  83. data/lib/generators/rails/resource_override.rb +10 -0
  84. data/lib/generators/rails/serializer_generator.rb +36 -0
  85. data/lib/generators/rails/templates/serializer.rb.erb +8 -0
  86. data/lib/grape/active_model_serializers.rb +14 -0
  87. data/lib/grape/formatters/active_model_serializers.rb +15 -0
  88. data/lib/grape/helpers/active_model_serializers.rb +16 -0
  89. data/test/action_controller/adapter_selector_test.rb +53 -0
  90. data/test/action_controller/explicit_serializer_test.rb +134 -0
  91. data/test/action_controller/json/include_test.rb +167 -0
  92. data/test/action_controller/json_api/deserialization_test.rb +59 -0
  93. data/test/action_controller/json_api/linked_test.rb +196 -0
  94. data/test/action_controller/json_api/pagination_test.rb +116 -0
  95. data/test/{serialization_scope_name_test.rb → action_controller/serialization_scope_name_test.rb} +11 -15
  96. data/test/action_controller/serialization_test.rb +435 -0
  97. data/test/active_model_serializers/logging_test.rb +77 -0
  98. data/test/active_model_serializers/model_test.rb +9 -0
  99. data/test/active_model_serializers/railtie_test_isolated.rb +57 -0
  100. data/test/active_model_serializers/serialization_context_test.rb +18 -0
  101. data/test/active_model_serializers/test/schema_test.rb +128 -0
  102. data/test/active_model_serializers/test/serializer_test.rb +63 -0
  103. data/test/active_record_test.rb +9 -0
  104. data/test/adapter/fragment_cache_test.rb +38 -0
  105. data/test/adapter/json/belongs_to_test.rb +47 -0
  106. data/test/adapter/json/collection_test.rb +92 -0
  107. data/test/adapter/json/has_many_test.rb +47 -0
  108. data/test/adapter/json_api/belongs_to_test.rb +157 -0
  109. data/test/adapter/json_api/collection_test.rb +97 -0
  110. data/test/adapter/json_api/fields_test.rb +89 -0
  111. data/test/adapter/json_api/has_many_embed_ids_test.rb +45 -0
  112. data/test/adapter/json_api/has_many_explicit_serializer_test.rb +98 -0
  113. data/test/adapter/json_api/has_many_test.rb +145 -0
  114. data/test/adapter/json_api/has_one_test.rb +81 -0
  115. data/test/adapter/json_api/json_api_test.rb +37 -0
  116. data/test/adapter/json_api/linked_test.rb +394 -0
  117. data/test/adapter/json_api/links_test.rb +68 -0
  118. data/test/adapter/json_api/pagination_links_test.rb +115 -0
  119. data/test/adapter/json_api/parse_test.rb +139 -0
  120. data/test/adapter/json_api/resource_type_config_test.rb +71 -0
  121. data/test/adapter/json_api/toplevel_jsonapi_test.rb +84 -0
  122. data/test/adapter/json_test.rb +47 -0
  123. data/test/adapter/null_test.rb +25 -0
  124. data/test/adapter_test.rb +42 -0
  125. data/test/array_serializer_test.rb +36 -73
  126. data/test/collection_serializer_test.rb +100 -0
  127. data/test/fixtures/active_record.rb +56 -0
  128. data/test/fixtures/poro.rb +229 -0
  129. data/test/generators/scaffold_controller_generator_test.rb +24 -0
  130. data/test/generators/serializer_generator_test.rb +57 -0
  131. data/test/grape_test.rb +82 -0
  132. data/test/include_tree/from_include_args_test.rb +26 -0
  133. data/test/include_tree/from_string_test.rb +94 -0
  134. data/test/include_tree/include_args_to_hash_test.rb +64 -0
  135. data/test/lint_test.rb +40 -0
  136. data/test/logger_test.rb +18 -0
  137. data/test/poro_test.rb +9 -0
  138. data/test/serializable_resource_test.rb +27 -0
  139. data/test/serializers/adapter_for_test.rb +166 -0
  140. data/test/serializers/association_macros_test.rb +36 -0
  141. data/test/serializers/associations_test.rb +267 -0
  142. data/test/serializers/attribute_test.rb +123 -0
  143. data/test/serializers/attributes_test.rb +52 -0
  144. data/test/serializers/cache_test.rb +209 -0
  145. data/test/serializers/configuration_test.rb +32 -0
  146. data/test/serializers/fieldset_test.rb +14 -0
  147. data/test/serializers/meta_test.rb +130 -0
  148. data/test/serializers/options_test.rb +21 -0
  149. data/test/serializers/root_test.rb +21 -0
  150. data/test/serializers/serializer_for_test.rb +134 -0
  151. data/test/support/custom_schemas/active_model_serializers/test/schema_test/my/index.json +6 -0
  152. data/test/support/isolated_unit.rb +77 -0
  153. data/test/support/rails5_shims.rb +29 -0
  154. data/test/support/rails_app.rb +25 -0
  155. data/test/support/schemas/active_model_serializers/test/schema_test/my/index.json +6 -0
  156. data/test/support/schemas/active_model_serializers/test/schema_test/my/show.json +6 -0
  157. data/test/support/schemas/custom/show.json +7 -0
  158. data/test/support/schemas/hyper_schema.json +93 -0
  159. data/test/support/schemas/render_using_json_api.json +43 -0
  160. data/test/support/schemas/simple_json_pointers.json +10 -0
  161. data/test/support/serialization_testing.rb +53 -0
  162. data/test/support/simplecov.rb +6 -0
  163. data/test/support/stream_capture.rb +50 -0
  164. data/test/support/test_case.rb +19 -0
  165. data/test/test_helper.rb +55 -24
  166. metadata +358 -42
  167. data/DESIGN.textile +0 -586
  168. data/Gemfile.edge +0 -9
  169. data/bench/perf.rb +0 -43
  170. data/cruft.md +0 -19
  171. data/lib/active_model/array_serializer.rb +0 -104
  172. data/lib/active_record/serializer_override.rb +0 -16
  173. data/lib/generators/resource_override.rb +0 -13
  174. data/lib/generators/serializer/USAGE +0 -9
  175. data/lib/generators/serializer/serializer_generator.rb +0 -42
  176. data/lib/generators/serializer/templates/serializer.rb +0 -19
  177. data/test/association_test.rb +0 -592
  178. data/test/caching_test.rb +0 -96
  179. data/test/generators_test.rb +0 -85
  180. data/test/no_serialization_scope_test.rb +0 -34
  181. data/test/serialization_test.rb +0 -392
  182. data/test/serializer_support_test.rb +0 -51
  183. data/test/serializer_test.rb +0 -1465
  184. data/test/test_fakes.rb +0 -217
@@ -0,0 +1,162 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # Adapters
4
+
5
+ ActiveModelSerializers offers the ability to configure which adapter
6
+ to use both globally and/or when serializing (usually when rendering).
7
+
8
+ The global adapter configuration is set on [`ActiveModelSerializers.config`](configuration_options.md).
9
+ It should be set only once, preferably at initialization.
10
+
11
+ For example:
12
+
13
+ ```ruby
14
+ ActiveModelSerializers.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
15
+ ```
16
+
17
+ or
18
+
19
+ ```ruby
20
+ ActiveModelSerializers.config.adapter = :json_api
21
+ ```
22
+
23
+ or
24
+
25
+ ```ruby
26
+ ActiveModelSerializers.config.adapter = :json
27
+ ```
28
+
29
+ The local adapter option is in the format `adapter: adapter`, where `adapter` is
30
+ any of the same values as set globally.
31
+
32
+ The configured adapter can be set as a symbol, class, or class name, as described in
33
+ [Advanced adapter configuration](adapters.md#advanced-adapter-configuration).
34
+
35
+ The `Attributes` adapter does not include a root key. It is just the serialized attributes.
36
+
37
+ Use either the `JSON` or `JSON API` adapters if you want the response document to have a root key.
38
+
39
+ ## Built in Adapters
40
+
41
+ ### Attributes - Default
42
+
43
+ It's the default adapter, it generates a json response without a root key.
44
+ Doesn't follow any specific convention.
45
+
46
+ ### JSON
47
+
48
+ The response document always with a root key.
49
+
50
+ The root key **can't be overridden**, and will be derived from the resource being serialized.
51
+
52
+ Doesn't follow any specific convention.
53
+
54
+ ### JSON API
55
+
56
+ This adapter follows **version 1.0** of the [format specified](../jsonapi/schema.md) in
57
+ [jsonapi.org/format](http://jsonapi.org/format).
58
+
59
+ #### Included
60
+
61
+ It will include the associated resources in the `"included"` member
62
+ when the resource names are included in the `include` option.
63
+ Including nested associated resources is also supported.
64
+
65
+ ```ruby
66
+ render json: @posts, include: ['author', 'comments', 'comments.author']
67
+ # or
68
+ render json: @posts, include: 'author,comments,comments.author'
69
+ ```
70
+
71
+ In addition, two types of wildcards may be used:
72
+
73
+ - `*` includes one level of associations.
74
+ - `**` includes all recursively.
75
+
76
+ These can be combined with other paths.
77
+
78
+ ```ruby
79
+ render json: @posts, include: '**' # or '*' for a single layer
80
+ ```
81
+
82
+ The format of the `include` option can be either:
83
+
84
+ - a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes).
85
+ - an Array of Symbols and Hashes.
86
+ - a mix of both.
87
+
88
+ The following would render posts and include:
89
+
90
+ - the author
91
+ - the author's comments, and
92
+ - every resource referenced by the author's comments (recursively).
93
+
94
+ It could be combined, like above, with other paths in any combination desired.
95
+
96
+ ```ruby
97
+ render json: @posts, include: 'author.comments.**'
98
+ ```
99
+
100
+ ##### Security Considerations
101
+
102
+ Since the included options may come from the query params (i.e. user-controller):
103
+
104
+ ```ruby
105
+ render json: @posts, include: params[:include]
106
+ ```
107
+
108
+ The user could pass in `include=**`.
109
+
110
+ We recommend filtering any user-supplied includes appropriately.
111
+
112
+ ## Advanced adapter configuration
113
+
114
+ ### Registering an adapter
115
+
116
+ The default adapter can be configured, as above, to use any class given to it.
117
+
118
+ An adapter may also be specified, e.g. when rendering, as a class or as a symbol.
119
+ If a symbol, then the adapter must be, e.g. `:great_example`,
120
+ `ActiveModel::Serializer::Adapter::GreatExample`, or registered.
121
+
122
+ There are two ways to register an adapter:
123
+
124
+ 1) The simplest, is to subclass `ActiveModel::Serializer::Adapter`, e.g. the below will
125
+ register the `Example::UsefulAdapter` as `:useful_adapter`.
126
+
127
+ ```ruby
128
+ module Example
129
+ class UsefulAdapter < ActiveModel::Serializer::Adapter
130
+ end
131
+ end
132
+ ```
133
+
134
+ You'll notice that the name it registers is the class name underscored, not the full namespace.
135
+
136
+ Under the covers, when the `ActiveModel::Serializer::Adapter` is subclassed, it registers
137
+ the subclass as `register(:useful_adapter, Example::UsefulAdapter)`
138
+
139
+ 2) Any class can be registered as an adapter by calling `register` directly on the
140
+ `ActiveModel::Serializer::Adapter` class. e.g., the below registers `MyAdapter` as
141
+ `:special_adapter`.
142
+
143
+ ```ruby
144
+ class MyAdapter; end
145
+ ActiveModel::Serializer::Adapter.register(:special_adapter, MyAdapter)
146
+ ```
147
+
148
+ ### Looking up an adapter
149
+
150
+ | Method | Return value |
151
+ | :------------ |:---------------|
152
+ | `ActiveModel::Serializer::Adapter.adapter_map` | A Hash of all known adapters `{ adapter_name => adapter_class }` |
153
+ | `ActiveModel::Serializer::Adapter.adapters` | A (sorted) Array of all known `adapter_names` |
154
+ | `ActiveModel::Serializer::Adapter.lookup(name_or_klass)` | The `adapter_class`, else raises an `ActiveModel::Serializer::Adapter::UnknownAdapter` error |
155
+ | `ActiveModel::Serializer::Adapter.adapter_class(adapter)` | Delegates to `ActiveModel::Serializer::Adapter.lookup(adapter)` |
156
+ | `ActiveModel::Serializer.adapter` | A convenience method for `ActiveModel::Serializer::Adapter.lookup(config.adapter)` |
157
+
158
+ The registered adapter name is always a String, but may be looked up as a Symbol or String.
159
+ Helpfully, the Symbol or String is underscored, so that `get(:my_adapter)` and `get("MyAdapter")`
160
+ may both be used.
161
+
162
+ For more information, see [the Adapter class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer/adapter.rb)
@@ -0,0 +1,52 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # Caching
4
+
5
+ To cache a serializer, call ```cache``` and pass its options.
6
+ The options are the same options of ```ActiveSupport::Cache::Store```, plus
7
+ a ```key``` option that will be the prefix of the object cache
8
+ on a pattern ```"#{key}/#{object.id}-#{object.updated_at}"```.
9
+
10
+ The cache support is optimized to use the cached object in multiple request. An object cached on a ```show``` request will be reused at the ```index```. If there is a relationship with another cached serializer it will also be created and reused automatically.
11
+
12
+ **[NOTE] Every object is individually cached.**
13
+
14
+ **[NOTE] The cache is automatically expired after an object is updated, but it's not deleted.**
15
+
16
+ ```ruby
17
+ cache(options = nil) # options: ```{key, expires_in, compress, force, race_condition_ttl}```
18
+ ```
19
+
20
+ Take the example bellow:
21
+
22
+ ```ruby
23
+ class PostSerializer < ActiveModel::Serializer
24
+ cache key: 'post', expires_in: 3.hours
25
+ attributes :title, :body
26
+
27
+ has_many :comments
28
+ end
29
+ ```
30
+
31
+ On this example every ```Post``` object will be cached with
32
+ the key ```"post/#{post.id}-#{post.updated_at}"```. You can use this key to expire it as you want,
33
+ but in this case it will be automatically expired after 3 hours.
34
+
35
+ ## Fragment Caching
36
+
37
+ If there is some API endpoint that shouldn't be fully cached, you can still optimise it, using Fragment Cache on the attributes and relationships that you want to cache.
38
+
39
+ You can define the attribute by using ```only``` or ```except``` option on cache method.
40
+
41
+ **[NOTE] Cache serializers will be used at their relationships**
42
+
43
+ Example:
44
+
45
+ ```ruby
46
+ class PostSerializer < ActiveModel::Serializer
47
+ cache key: 'post', expires_in: 3.hours, only: [:title]
48
+ attributes :title, :body
49
+
50
+ has_many :comments
51
+ end
52
+ ```
@@ -0,0 +1,27 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # Configuration Options
4
+
5
+ The following configuration options can be set on `ActiveModelSerializers.config`,
6
+ preferably inside an initializer.
7
+
8
+ ## General
9
+
10
+ - `adapter`: The [adapter](adapters.md) to use. Possible values: `:attributes, :json, :json_api`. Default: `:attributes`.
11
+ - `serializer_lookup_enabled`: When `false`, serializers must be explicitly specified. Default: `true`
12
+
13
+ ## JSON API
14
+
15
+ - `jsonapi_resource_type`: Whether the `type` attributes of resources should be singular or plural. Possible values: `:singular, :plural`. Default: `:plural`.
16
+ - `jsonapi_include_toplevel_object`: Whether to include a [top level JSON API member](http://jsonapi.org/format/#document-jsonapi-object)
17
+ in the response document.
18
+ Default: `false`.
19
+ - Used when `jsonapi_include_toplevel_object` is `true`:
20
+ - `jsonapi_version`: The latest version of the spec the API conforms to.
21
+ Default: `'1.0'`.
22
+ - `jsonapi_toplevel_meta`: Optional metadata. Not included if empty.
23
+ Default: `{}`.
24
+
25
+ ## Hooks
26
+
27
+ To run a hook when ActiveModelSerializers is loaded, use `ActiveSupport.on_load(:action_controller) do end`
@@ -0,0 +1,98 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # Getting Started
4
+
5
+ ## Creating a Serializer
6
+
7
+ The easiest way to create a new serializer is to generate a new resource, which
8
+ will generate a serializer at the same time:
9
+
10
+ ```
11
+ $ rails g resource post title:string body:string
12
+ ```
13
+
14
+ This will generate a serializer in `app/serializers/post_serializer.rb` for
15
+ your new model. You can also generate a serializer for an existing model with
16
+ the serializer generator:
17
+
18
+ ```
19
+ $ rails g serializer post
20
+ ```
21
+
22
+ The generated serializer will contain basic `attributes` and
23
+ `has_many`/`has_one`/`belongs_to` declarations, based on the model. For example:
24
+
25
+ ```ruby
26
+ class PostSerializer < ActiveModel::Serializer
27
+ attributes :title, :body
28
+
29
+ has_many :comments
30
+ has_one :author
31
+ end
32
+ ```
33
+
34
+ and
35
+
36
+ ```ruby
37
+ class CommentSerializer < ActiveModel::Serializer
38
+ attributes :name, :body
39
+
40
+ belongs_to :post_id
41
+ end
42
+ ```
43
+
44
+ The attribute names are a **whitelist** of attributes to be serialized.
45
+
46
+ The `has_many`, `has_one`, and `belongs_to` declarations describe relationships between
47
+ resources. By default, when you serialize a `Post`, you will get its `Comments`
48
+ as well.
49
+
50
+ For more information, see [Serializers](/docs/general/serializers.md).
51
+
52
+ ### Namespaced Models
53
+
54
+ When serializing a model inside a namespace, such as `Api::V1::Post`, ActiveModelSerializers will expect the corresponding serializer to be inside the same namespace (namely `Api::V1::PostSerializer`).
55
+
56
+ ### Model Associations and Nested Serializers
57
+
58
+ When declaring a serializer for a model with associations, such as:
59
+ ```ruby
60
+ class PostSerializer < ActiveModel::Serializer
61
+ has_many :comments
62
+ end
63
+ ```
64
+ ActiveModelSerializers will look for `PostSerializer::CommentSerializer` in priority, and fall back to `::CommentSerializer` in case the former does not exist. This allows for more control over the way a model gets serialized as an association of an other model.
65
+
66
+ For example, in the following situation:
67
+
68
+ ```ruby
69
+ class CommentSerializer < ActiveModel::Serializer
70
+ attributes :body, :date, :nb_likes
71
+ end
72
+
73
+ class PostSerializer < ActiveModel::Serializer
74
+ has_many :comments
75
+ class CommentSerializer < ActiveModel::Serializer
76
+ attributes :body_short
77
+ end
78
+ end
79
+ ```
80
+
81
+ ActiveModelSerializers will use `PostSerializer::CommentSerializer` (thus including only the `:body_short` attribute) when serializing a `Comment` as part of a `Post`, but use `::CommentSerializer` when serializing a `Comment` directly (thus including `:body, :date, :nb_likes`).
82
+
83
+ ## Rails Integration
84
+
85
+ ActiveModelSerializers will automatically integrate with your Rails app,
86
+ so you won't need to update your controller.
87
+ This is a example of how the controller will look:
88
+
89
+ ```ruby
90
+ class PostsController < ApplicationController
91
+
92
+ def show
93
+ @post = Post.find(params[:id])
94
+ render json: @post
95
+ end
96
+
97
+ end
98
+ ```
@@ -0,0 +1,40 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # Instrumentation
4
+
5
+ ActiveModelSerializers uses the
6
+ [ActiveSupport::Notification API](http://guides.rubyonrails.org/active_support_instrumentation.html#subscribing-to-an-event),
7
+ which allows for subscribing to events, such as for logging.
8
+
9
+ ## Events
10
+
11
+ Name:
12
+
13
+ `render.active_model_serializers`
14
+
15
+ Payload (example):
16
+
17
+ ```ruby
18
+ {
19
+ serializer: PostSerializer,
20
+ adapter: ActiveModel::Serializer::Adapter::Attributes
21
+ }
22
+ ```
23
+
24
+ Subscribing:
25
+
26
+ ```ruby
27
+ ActiveSupport::Notifications.subscribe 'render.active_model_serializers' do |name, started, finished, unique_id, data|
28
+ # whatever
29
+ end
30
+ ActiveSupport::Notifications.subscribe 'render.active_model_serializers' do |*args|
31
+ event = ActiveSupport::Notifications::Event.new(*args)
32
+ # event.payload
33
+ # whatever
34
+ end
35
+ ```
36
+
37
+ ## [LogSubscriber](http://api.rubyonrails.org/classes/ActiveSupport/LogSubscriber.html)
38
+
39
+ ActiveModelSerializers includes an `ActiveModelSerializers::LogSubscriber` that attaches to
40
+ `render.active_model_serializers`.
@@ -0,0 +1,14 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # Logging
4
+
5
+ The default logger in a Rails application will be `Rails.logger`.
6
+
7
+ When there is no `Rails.logger`, the default logger is an instance of
8
+ `ActiveSupport::TaggedLogging` logging to STDOUT.
9
+
10
+ You may customize the logger in an initializer, for example:
11
+
12
+ ```ruby
13
+ ActiveModelSerializers.logger = Logger.new(STDOUT)
14
+ ```
@@ -0,0 +1,153 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # Rendering
4
+
5
+ ### Implicit Serializer
6
+
7
+ In your controllers, when you use `render :json`, Rails will now first search
8
+ for a serializer for the object and use it if available.
9
+
10
+ ```ruby
11
+ class PostsController < ApplicationController
12
+ def show
13
+ @post = Post.find(params[:id])
14
+
15
+ render json: @post
16
+ end
17
+ end
18
+ ```
19
+
20
+ In this case, Rails will look for a serializer named `PostSerializer`, and if
21
+ it exists, use it to serialize the `Post`.
22
+
23
+ ### Explicit Serializer
24
+
25
+ If you wish to use a serializer other than the default, you can explicitly pass it to the renderer.
26
+
27
+ #### 1. For a resource:
28
+
29
+ ```ruby
30
+ render json: @post, serializer: PostPreviewSerializer
31
+ ```
32
+
33
+ #### 2. For a resource collection:
34
+
35
+ Specify the serializer for each resource with `each_serializer`
36
+
37
+ ```ruby
38
+ render json: @posts, each_serializer: PostPreviewSerializer
39
+ ```
40
+
41
+ The default serializer for collections is `CollectionSerializer`.
42
+
43
+ Specify the collection serializer with the `serializer` option.
44
+
45
+ ```ruby
46
+ render json: @posts, serializer: CollectionSerializer, each_serializer: PostPreviewSerializer
47
+ ```
48
+
49
+ ## Serializing non-ActiveRecord objects
50
+
51
+ All serializable resources must pass the
52
+ [ActiveModel::Serializer::Lint::Tests](../../lib/active_model/serializer/lint.rb#L17).
53
+
54
+ See the ActiveModelSerializers::Model for a base class that implements the full
55
+ API for a plain-old Ruby object (PORO).
56
+
57
+ ## SerializableResource options
58
+
59
+ The `options` hash passed to `render` or `ActiveModel::SerializableResource.new(resource, options)`
60
+ are partitioned into `serializer_opts` and `adapter_opts`. `adapter_opts` are passed to new Adapters;
61
+ `serializer_opts` are passed to new Serializers.
62
+
63
+ The `adapter_opts` are specified in [ActiveModel::SerializableResource::ADAPTER_OPTIONS](../../lib/active_model/serializable_resource.rb#L4).
64
+ The `serializer_opts` are the remaining options.
65
+
66
+ (In Rails, the `options` are also passed to the `as_json(options)` or `to_json(options)`
67
+ methods on the resource serialization by the Rails JSON renderer. They are, therefore, important
68
+ to know about, but not part of ActiveModelSerializers.)
69
+
70
+ See [ARCHITECTURE](../ARCHITECTURE.md) for more information.
71
+
72
+ ### adapter_opts
73
+
74
+ #### fields
75
+
76
+ PR please :)
77
+
78
+ #### adapter
79
+
80
+ PR please :)
81
+
82
+ #### meta
83
+
84
+ If you want a `meta` attribute in your response, specify it in the `render`
85
+ call:
86
+
87
+ ```ruby
88
+ render json: @post, meta: { total: 10 }
89
+ ```
90
+
91
+ The key can be customized using `meta_key` option.
92
+
93
+ ```ruby
94
+ render json: @post, meta: { total: 10 }, meta_key: "custom_meta"
95
+ ```
96
+
97
+ `meta` will only be included in your response if you are using an Adapter that supports `root`,
98
+ as JsonAPI and Json adapters, the default adapter (Attributes) doesn't have `root`.
99
+
100
+ #### meta_key
101
+
102
+ PR please :)
103
+
104
+ #### links
105
+
106
+ PR please :)
107
+
108
+ ### serializer_opts
109
+
110
+ #### include
111
+
112
+ PR please :)
113
+
114
+ #### root
115
+
116
+ The resource root is derived from the class name of the resource being serialized.
117
+ e.g. `UserPostSerializer.new(UserPost.new)` will be serialized with the root `user_post` or `user_posts` according the adapter collection pluralization rules.
118
+
119
+ Specify the root by passing it as an argument to `render`. For example:
120
+
121
+ ```ruby
122
+ render json: @user_post, root: "admin_post", adapter: :json
123
+ ```
124
+
125
+ This will be rendered as:
126
+ ```json
127
+ {
128
+ "admin_post": {
129
+ "title": "how to do open source"
130
+ }
131
+ }
132
+ ```
133
+ Note: the `Attributes` adapter (default) does not include a resource root.
134
+
135
+ #### serializer
136
+
137
+ PR please :)
138
+
139
+ #### scope
140
+
141
+ PR please :)
142
+
143
+ #### scope_name
144
+
145
+ PR please :)
146
+
147
+ ## Using a serializer without `render`
148
+
149
+ See [Usage outside of a controller](../howto/outside_controller_use.md#serializing-before-controller-render).
150
+
151
+ ## Pagination
152
+
153
+ See [How to add pagination links](https://github.com/rails-api/active_model_serializers/blob/master/docs/howto/add_pagination_links.md).