active_model_serializers_custom 0.10.90

Sign up to get free protection for your applications and to get access to all the features.
Files changed (215) hide show
  1. checksums.yaml +7 -0
  2. data/.github/ISSUE_TEMPLATE.md +29 -0
  3. data/.github/PULL_REQUEST_TEMPLATE.md +15 -0
  4. data/.gitignore +35 -0
  5. data/.rubocop.yml +109 -0
  6. data/.simplecov +110 -0
  7. data/.travis.yml +63 -0
  8. data/CHANGELOG.md +727 -0
  9. data/CODE_OF_CONDUCT.md +74 -0
  10. data/CONTRIBUTING.md +105 -0
  11. data/Gemfile +74 -0
  12. data/MIT-LICENSE +22 -0
  13. data/README.md +305 -0
  14. data/Rakefile +76 -0
  15. data/active_model_serializers.gemspec +64 -0
  16. data/appveyor.yml +28 -0
  17. data/bin/bench +171 -0
  18. data/bin/bench_regression +316 -0
  19. data/bin/rubocop +38 -0
  20. data/bin/serve_benchmark +39 -0
  21. data/docs/README.md +41 -0
  22. data/docs/STYLE.md +58 -0
  23. data/docs/general/adapters.md +269 -0
  24. data/docs/general/caching.md +58 -0
  25. data/docs/general/configuration_options.md +185 -0
  26. data/docs/general/deserialization.md +100 -0
  27. data/docs/general/fields.md +31 -0
  28. data/docs/general/getting_started.md +133 -0
  29. data/docs/general/instrumentation.md +40 -0
  30. data/docs/general/key_transforms.md +40 -0
  31. data/docs/general/logging.md +21 -0
  32. data/docs/general/rendering.md +293 -0
  33. data/docs/general/serializers.md +495 -0
  34. data/docs/how-open-source-maintained.jpg +0 -0
  35. data/docs/howto/add_pagination_links.md +138 -0
  36. data/docs/howto/add_relationship_links.md +140 -0
  37. data/docs/howto/add_root_key.md +62 -0
  38. data/docs/howto/grape_integration.md +42 -0
  39. data/docs/howto/outside_controller_use.md +66 -0
  40. data/docs/howto/passing_arbitrary_options.md +27 -0
  41. data/docs/howto/serialize_poro.md +73 -0
  42. data/docs/howto/test.md +154 -0
  43. data/docs/howto/upgrade_from_0_8_to_0_10.md +265 -0
  44. data/docs/integrations/ember-and-json-api.md +147 -0
  45. data/docs/integrations/grape.md +19 -0
  46. data/docs/jsonapi/errors.md +56 -0
  47. data/docs/jsonapi/schema.md +151 -0
  48. data/docs/jsonapi/schema/schema.json +366 -0
  49. data/docs/rfcs/0000-namespace.md +106 -0
  50. data/docs/rfcs/template.md +15 -0
  51. data/lib/action_controller/serialization.rb +76 -0
  52. data/lib/active_model/serializable_resource.rb +13 -0
  53. data/lib/active_model/serializer.rb +418 -0
  54. data/lib/active_model/serializer/adapter.rb +26 -0
  55. data/lib/active_model/serializer/adapter/attributes.rb +17 -0
  56. data/lib/active_model/serializer/adapter/base.rb +20 -0
  57. data/lib/active_model/serializer/adapter/json.rb +17 -0
  58. data/lib/active_model/serializer/adapter/json_api.rb +17 -0
  59. data/lib/active_model/serializer/adapter/null.rb +17 -0
  60. data/lib/active_model/serializer/array_serializer.rb +14 -0
  61. data/lib/active_model/serializer/association.rb +91 -0
  62. data/lib/active_model/serializer/attribute.rb +27 -0
  63. data/lib/active_model/serializer/belongs_to_reflection.rb +13 -0
  64. data/lib/active_model/serializer/collection_serializer.rb +90 -0
  65. data/lib/active_model/serializer/concerns/caching.rb +304 -0
  66. data/lib/active_model/serializer/error_serializer.rb +16 -0
  67. data/lib/active_model/serializer/errors_serializer.rb +34 -0
  68. data/lib/active_model/serializer/field.rb +92 -0
  69. data/lib/active_model/serializer/fieldset.rb +33 -0
  70. data/lib/active_model/serializer/has_many_reflection.rb +12 -0
  71. data/lib/active_model/serializer/has_one_reflection.rb +9 -0
  72. data/lib/active_model/serializer/lazy_association.rb +99 -0
  73. data/lib/active_model/serializer/link.rb +23 -0
  74. data/lib/active_model/serializer/lint.rb +152 -0
  75. data/lib/active_model/serializer/null.rb +19 -0
  76. data/lib/active_model/serializer/reflection.rb +212 -0
  77. data/lib/active_model/serializer/version.rb +7 -0
  78. data/lib/active_model_serializers.rb +63 -0
  79. data/lib/active_model_serializers/adapter.rb +100 -0
  80. data/lib/active_model_serializers/adapter/attributes.rb +15 -0
  81. data/lib/active_model_serializers/adapter/base.rb +85 -0
  82. data/lib/active_model_serializers/adapter/json.rb +23 -0
  83. data/lib/active_model_serializers/adapter/json_api.rb +535 -0
  84. data/lib/active_model_serializers/adapter/json_api/deserialization.rb +215 -0
  85. data/lib/active_model_serializers/adapter/json_api/error.rb +98 -0
  86. data/lib/active_model_serializers/adapter/json_api/jsonapi.rb +51 -0
  87. data/lib/active_model_serializers/adapter/json_api/link.rb +85 -0
  88. data/lib/active_model_serializers/adapter/json_api/meta.rb +39 -0
  89. data/lib/active_model_serializers/adapter/json_api/pagination_links.rb +90 -0
  90. data/lib/active_model_serializers/adapter/json_api/relationship.rb +106 -0
  91. data/lib/active_model_serializers/adapter/json_api/resource_identifier.rb +68 -0
  92. data/lib/active_model_serializers/adapter/null.rb +11 -0
  93. data/lib/active_model_serializers/callbacks.rb +57 -0
  94. data/lib/active_model_serializers/deprecate.rb +56 -0
  95. data/lib/active_model_serializers/deserialization.rb +17 -0
  96. data/lib/active_model_serializers/json_pointer.rb +16 -0
  97. data/lib/active_model_serializers/logging.rb +124 -0
  98. data/lib/active_model_serializers/lookup_chain.rb +82 -0
  99. data/lib/active_model_serializers/model.rb +132 -0
  100. data/lib/active_model_serializers/railtie.rb +52 -0
  101. data/lib/active_model_serializers/register_jsonapi_renderer.rb +80 -0
  102. data/lib/active_model_serializers/serializable_resource.rb +84 -0
  103. data/lib/active_model_serializers/serialization_context.rb +41 -0
  104. data/lib/active_model_serializers/test.rb +9 -0
  105. data/lib/active_model_serializers/test/schema.rb +140 -0
  106. data/lib/active_model_serializers/test/serializer.rb +127 -0
  107. data/lib/generators/rails/USAGE +6 -0
  108. data/lib/generators/rails/resource_override.rb +12 -0
  109. data/lib/generators/rails/serializer_generator.rb +38 -0
  110. data/lib/generators/rails/templates/serializer.rb.erb +8 -0
  111. data/lib/grape/active_model_serializers.rb +18 -0
  112. data/lib/grape/formatters/active_model_serializers.rb +34 -0
  113. data/lib/grape/helpers/active_model_serializers.rb +19 -0
  114. data/lib/tasks/rubocop.rake +55 -0
  115. data/test/action_controller/adapter_selector_test.rb +64 -0
  116. data/test/action_controller/explicit_serializer_test.rb +137 -0
  117. data/test/action_controller/json/include_test.rb +248 -0
  118. data/test/action_controller/json_api/deserialization_test.rb +114 -0
  119. data/test/action_controller/json_api/errors_test.rb +42 -0
  120. data/test/action_controller/json_api/fields_test.rb +68 -0
  121. data/test/action_controller/json_api/linked_test.rb +204 -0
  122. data/test/action_controller/json_api/pagination_test.rb +126 -0
  123. data/test/action_controller/json_api/transform_test.rb +191 -0
  124. data/test/action_controller/lookup_proc_test.rb +51 -0
  125. data/test/action_controller/namespace_lookup_test.rb +239 -0
  126. data/test/action_controller/serialization_scope_name_test.rb +237 -0
  127. data/test/action_controller/serialization_test.rb +480 -0
  128. data/test/active_model_serializers/adapter_for_test.rb +210 -0
  129. data/test/active_model_serializers/json_pointer_test.rb +24 -0
  130. data/test/active_model_serializers/logging_test.rb +79 -0
  131. data/test/active_model_serializers/model_test.rb +144 -0
  132. data/test/active_model_serializers/railtie_test_isolated.rb +70 -0
  133. data/test/active_model_serializers/register_jsonapi_renderer_test_isolated.rb +163 -0
  134. data/test/active_model_serializers/serialization_context_test_isolated.rb +73 -0
  135. data/test/active_model_serializers/test/schema_test.rb +133 -0
  136. data/test/active_model_serializers/test/serializer_test.rb +64 -0
  137. data/test/active_record_test.rb +11 -0
  138. data/test/adapter/attributes_test.rb +42 -0
  139. data/test/adapter/deprecation_test.rb +102 -0
  140. data/test/adapter/json/belongs_to_test.rb +47 -0
  141. data/test/adapter/json/collection_test.rb +106 -0
  142. data/test/adapter/json/has_many_test.rb +55 -0
  143. data/test/adapter/json/transform_test.rb +95 -0
  144. data/test/adapter/json_api/belongs_to_test.rb +157 -0
  145. data/test/adapter/json_api/collection_test.rb +98 -0
  146. data/test/adapter/json_api/errors_test.rb +78 -0
  147. data/test/adapter/json_api/fields_test.rb +98 -0
  148. data/test/adapter/json_api/has_many_explicit_serializer_test.rb +98 -0
  149. data/test/adapter/json_api/has_many_test.rb +175 -0
  150. data/test/adapter/json_api/has_one_test.rb +82 -0
  151. data/test/adapter/json_api/include_data_if_sideloaded_test.rb +215 -0
  152. data/test/adapter/json_api/json_api_test.rb +35 -0
  153. data/test/adapter/json_api/linked_test.rb +415 -0
  154. data/test/adapter/json_api/links_test.rb +112 -0
  155. data/test/adapter/json_api/pagination_links_test.rb +208 -0
  156. data/test/adapter/json_api/parse_test.rb +139 -0
  157. data/test/adapter/json_api/relationship_test.rb +399 -0
  158. data/test/adapter/json_api/resource_meta_test.rb +102 -0
  159. data/test/adapter/json_api/toplevel_jsonapi_test.rb +84 -0
  160. data/test/adapter/json_api/transform_test.rb +514 -0
  161. data/test/adapter/json_api/type_test.rb +195 -0
  162. data/test/adapter/json_test.rb +48 -0
  163. data/test/adapter/null_test.rb +24 -0
  164. data/test/adapter/polymorphic_test.rb +220 -0
  165. data/test/adapter_test.rb +69 -0
  166. data/test/array_serializer_test.rb +24 -0
  167. data/test/benchmark/app.rb +67 -0
  168. data/test/benchmark/benchmarking_support.rb +69 -0
  169. data/test/benchmark/bm_active_record.rb +83 -0
  170. data/test/benchmark/bm_adapter.rb +40 -0
  171. data/test/benchmark/bm_caching.rb +121 -0
  172. data/test/benchmark/bm_lookup_chain.rb +85 -0
  173. data/test/benchmark/bm_transform.rb +47 -0
  174. data/test/benchmark/config.ru +3 -0
  175. data/test/benchmark/controllers.rb +85 -0
  176. data/test/benchmark/fixtures.rb +221 -0
  177. data/test/cache_test.rb +717 -0
  178. data/test/collection_serializer_test.rb +129 -0
  179. data/test/fixtures/active_record.rb +115 -0
  180. data/test/fixtures/poro.rb +227 -0
  181. data/test/generators/scaffold_controller_generator_test.rb +26 -0
  182. data/test/generators/serializer_generator_test.rb +77 -0
  183. data/test/grape_test.rb +198 -0
  184. data/test/lint_test.rb +51 -0
  185. data/test/logger_test.rb +22 -0
  186. data/test/poro_test.rb +11 -0
  187. data/test/serializable_resource_test.rb +81 -0
  188. data/test/serializers/association_macros_test.rb +39 -0
  189. data/test/serializers/associations_test.rb +520 -0
  190. data/test/serializers/attribute_test.rb +155 -0
  191. data/test/serializers/attributes_test.rb +54 -0
  192. data/test/serializers/caching_configuration_test_isolated.rb +172 -0
  193. data/test/serializers/configuration_test.rb +34 -0
  194. data/test/serializers/fieldset_test.rb +16 -0
  195. data/test/serializers/meta_test.rb +204 -0
  196. data/test/serializers/options_test.rb +34 -0
  197. data/test/serializers/read_attribute_for_serialization_test.rb +81 -0
  198. data/test/serializers/reflection_test.rb +481 -0
  199. data/test/serializers/root_test.rb +23 -0
  200. data/test/serializers/serialization_test.rb +57 -0
  201. data/test/serializers/serializer_for_test.rb +138 -0
  202. data/test/serializers/serializer_for_with_namespace_test.rb +90 -0
  203. data/test/support/custom_schemas/active_model_serializers/test/schema_test/my/index.json +6 -0
  204. data/test/support/isolated_unit.rb +86 -0
  205. data/test/support/rails5_shims.rb +55 -0
  206. data/test/support/rails_app.rb +40 -0
  207. data/test/support/schemas/active_model_serializers/test/schema_test/my/index.json +6 -0
  208. data/test/support/schemas/active_model_serializers/test/schema_test/my/show.json +6 -0
  209. data/test/support/schemas/custom/show.json +7 -0
  210. data/test/support/schemas/hyper_schema.json +93 -0
  211. data/test/support/schemas/render_using_json_api.json +43 -0
  212. data/test/support/schemas/simple_json_pointers.json +10 -0
  213. data/test/support/serialization_testing.rb +81 -0
  214. data/test/test_helper.rb +72 -0
  215. metadata +622 -0
@@ -0,0 +1,138 @@
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.
@@ -0,0 +1,140 @@
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
+ end
19
+ ```
20
+
21
+ Bear in mind though that ActiveModelSerializers are [framework-agnostic](outside_controller_use.md), Rails is just a common example here.
22
+
23
+ ### Links as an attribute of a resource
24
+ **This is applicable to JSON and Attributes adapters**
25
+
26
+ You can define an attribute in the resource, named `links`.
27
+
28
+ ```ruby
29
+ class Api::V1::UserSerializer < ActiveModel::Serializer
30
+ include Rails.application.routes.url_helpers
31
+
32
+ attributes :id, :name
33
+
34
+ attribute :links do
35
+ id = object.id
36
+ {
37
+ self: api_v1_user_path(id),
38
+ microposts: api_v1_microposts_path(user_id: id)
39
+ }
40
+ end
41
+ end
42
+ ```
43
+
44
+ Using the `JSON` adapter, this will result in:
45
+
46
+ ```json
47
+ {
48
+ "user": {
49
+ "id": "1",
50
+ "name": "John",
51
+ "links": {
52
+ "self": "/api/v1/users/1",
53
+ "microposts": "/api/v1/microposts?user_id=1"
54
+ }
55
+ }
56
+ }
57
+ ```
58
+
59
+
60
+ ### Links as a property of the resource definiton
61
+ **This is only applicable to JSONAPI adapter**
62
+
63
+ You can use the `link` class method to define the links you need in the resource's primary data.
64
+
65
+ ```ruby
66
+ class Api::V1::UserSerializer < ActiveModel::Serializer
67
+ attributes :id, :name
68
+
69
+ link(:self) { api_v1_user_path(object.id) }
70
+ link(:microposts) { api_v1_microposts_path(user_id: object.id) }
71
+ end
72
+ ```
73
+
74
+ Using the `JSONAPI` adapter, this will result in:
75
+
76
+ ```json
77
+ {
78
+ "data": {
79
+ "id": "1",
80
+ "type": "users",
81
+ "attributes": {
82
+ "name": "Example User"
83
+ },
84
+ "links": {
85
+ "self": "/api/v1/users/1",
86
+ "microposts": "/api/v1/microposts?user_id=1"
87
+ }
88
+ }
89
+ }
90
+ ```
91
+
92
+ ### Links that follow the JSONAPI spec
93
+ **This is only applicable to JSONAPI adapter**
94
+
95
+ If you have a JSONAPI-strict client that you are working with (like `ember-data`)
96
+ you need to construct the links inside the relationships. Also the link to fetch the
97
+ relationship data must be under the `related` attribute, whereas to manipulate the
98
+ relationship (in case of many-to-many relationship) must be under the `self` attribute.
99
+
100
+ You can find more info in the [spec](http://jsonapi.org/format/#document-resource-object-relationships).
101
+
102
+ Here is how you can do this:
103
+
104
+ ```ruby
105
+ class Api::V1::UserSerializer < ActiveModel::Serializer
106
+ attributes :id, :name
107
+
108
+ has_many :microposts, serializer: Api::V1::MicropostSerializer do
109
+ link(:related) { api_v1_microposts_path(user_id: object.id) }
110
+
111
+ microposts = object.microposts
112
+ # The following code is needed to avoid n+1 queries.
113
+ # Core devs are working to remove this necessity.
114
+ # See: https://github.com/rails-api/active_model_serializers/issues/1325
115
+ microposts.loaded? ? microposts : microposts.none
116
+ end
117
+ end
118
+ ```
119
+
120
+ This will result in:
121
+
122
+ ```json
123
+ {
124
+ "data": {
125
+ "id": "1",
126
+ "type": "users",
127
+ "attributes": {
128
+ "name": "Example User"
129
+ },
130
+ "relationships": {
131
+ "microposts": {
132
+ "data": [],
133
+ "links": {
134
+ "related": "/api/v1/microposts?user_id=1"
135
+ }
136
+ }
137
+ }
138
+ }
139
+ }
140
+ ```
@@ -0,0 +1,62 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ # How to add root key
4
+
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:
6
+
7
+ ```json
8
+ {
9
+ "id": 1,
10
+ "title": "Awesome Post Tile",
11
+ "content": "Post content"
12
+ }
13
+ ```
14
+
15
+ In order to add the root key you need to use the ```JSON``` Adapter, you can change this in an initializer:
16
+
17
+ ```ruby
18
+ ActiveModelSerializers.config.adapter = :json
19
+ ```
20
+
21
+ Note that adapter configuration has no effect on a serializer that is called
22
+ directly, e.g. in a serializer unit test. Instead, something like
23
+ `UserSerializer.new(user).as_json` will *always* behave as if the adapter were
24
+ the 'Attributes' adapter. See [Outside Controller
25
+ Usage](../howto/outside_controller_use.md) for more details on recommended
26
+ usage.
27
+
28
+ You can also specify a class as adapter, as long as it complies with the ActiveModelSerializers adapters interface.
29
+ It will add the root key to all your serialized endpoints.
30
+
31
+ ex:
32
+
33
+ ```json
34
+ {
35
+ "post": {
36
+ "id": 1,
37
+ "title": "Awesome Post Tile",
38
+ "content": "Post content"
39
+ }
40
+ }
41
+ ```
42
+
43
+ or if it returns a collection:
44
+
45
+ ```json
46
+ {
47
+ "posts": [
48
+ {
49
+ "id": 1,
50
+ "title": "Awesome Post Tile",
51
+ "content": "Post content"
52
+ },
53
+ {
54
+ "id": 2,
55
+ "title": "Another Post Tile",
56
+ "content": "Another post content"
57
+ }
58
+ ]
59
+ }
60
+ ```
61
+
62
+ [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
+ ```
@@ -0,0 +1,66 @@
1
+ [Back to Guides](../README.md)
2
+
3
+ ## Using ActiveModelSerializers Outside Of A Controller
4
+
5
+ ### Serializing a resource
6
+
7
+ In ActiveModelSerializers versions 0.10 or later, serializing resources outside of the controller context is fairly simple:
8
+
9
+ ```ruby
10
+ # Create our resource
11
+ post = Post.create(title: "Sample post", body: "I love Active Model Serializers!")
12
+
13
+ # Optional options parameters for both the serializer and instance
14
+ options = {serializer: PostDetailedSerializer, username: 'sample user'}
15
+
16
+ # Create a serializable resource instance
17
+ serializable_resource = ActiveModelSerializers::SerializableResource.new(post, options)
18
+
19
+ # Convert your resource into json
20
+ model_json = serializable_resource.as_json
21
+ ```
22
+ The object that is passed to `ActiveModelSerializers::SerializableResource.new` can be a single resource or a collection.
23
+ The additional options are the same options that are passed [through controllers](../general/rendering.md#explicit-serializer).
24
+
25
+ ### Looking up the Serializer for a Resource
26
+
27
+ If you want to retrieve the serializer class for a specific resource, you can do the following:
28
+
29
+ ```ruby
30
+ # Create our resource
31
+ post = Post.create(title: "Another Example", body: "So much fun.")
32
+
33
+ # Optional options parameters
34
+ options = {}
35
+
36
+ # Retrieve the default serializer for posts
37
+ serializer = ActiveModel::Serializer.serializer_for(post, options)
38
+ ```
39
+
40
+ You could also retrieve the serializer via:
41
+
42
+ ```ruby
43
+ ActiveModelSerializers::SerializableResource.new(post, options).serializer
44
+ ```
45
+
46
+ Both approaches will return the serializer class that will be used for the resource.
47
+
48
+ Additionally, you could retrieve the serializer instance for the resource via:
49
+
50
+ ```ruby
51
+ ActiveModelSerializers::SerializableResource.new(post, options).serializer_instance
52
+ ```
53
+
54
+ ## Serializing before controller render
55
+
56
+ At times, you might want to use a serializer without rendering it to the view. For those cases, you can create an instance of `ActiveModelSerializers::SerializableResource` with
57
+ the resource you want to be serialized and call `.as_json`.
58
+
59
+ ```ruby
60
+ def create
61
+ message = current_user.messages.create!(message_params)
62
+ message_json = ActiveModelSerializers::SerializableResource.new(message).as_json
63
+ MessageCreationWorker.perform(message_json)
64
+ head 204
65
+ end
66
+ ```