active_model_serializers 0.10.0 → 0.10.12

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 +5 -5
  2. data/CHANGELOG.md +233 -2
  3. data/README.md +171 -33
  4. data/lib/action_controller/serialization.rb +23 -3
  5. data/lib/active_model/serializable_resource.rb +2 -0
  6. data/lib/active_model/serializer/adapter/attributes.rb +2 -0
  7. data/lib/active_model/serializer/adapter/base.rb +4 -0
  8. data/lib/active_model/serializer/adapter/json.rb +2 -0
  9. data/lib/active_model/serializer/adapter/json_api.rb +2 -0
  10. data/lib/active_model/serializer/adapter/null.rb +2 -0
  11. data/lib/active_model/serializer/adapter.rb +2 -0
  12. data/lib/active_model/serializer/array_serializer.rb +10 -5
  13. data/lib/active_model/serializer/association.rb +64 -10
  14. data/lib/active_model/serializer/attribute.rb +2 -0
  15. data/lib/active_model/serializer/belongs_to_reflection.rb +6 -3
  16. data/lib/active_model/serializer/collection_serializer.rb +39 -13
  17. data/lib/active_model/serializer/{caching.rb → concerns/caching.rb} +89 -117
  18. data/lib/active_model/serializer/error_serializer.rb +13 -7
  19. data/lib/active_model/serializer/errors_serializer.rb +27 -20
  20. data/lib/active_model/serializer/field.rb +2 -0
  21. data/lib/active_model/serializer/fieldset.rb +3 -1
  22. data/lib/active_model/serializer/has_many_reflection.rb +5 -3
  23. data/lib/active_model/serializer/has_one_reflection.rb +3 -4
  24. data/lib/active_model/serializer/lazy_association.rb +99 -0
  25. data/lib/active_model/serializer/link.rb +23 -0
  26. data/lib/active_model/serializer/lint.rb +136 -130
  27. data/lib/active_model/serializer/null.rb +2 -0
  28. data/lib/active_model/serializer/reflection.rb +130 -65
  29. data/lib/active_model/serializer/version.rb +3 -1
  30. data/lib/active_model/serializer.rb +319 -86
  31. data/lib/active_model_serializers/adapter/attributes.rb +17 -57
  32. data/lib/active_model_serializers/adapter/base.rb +41 -39
  33. data/lib/active_model_serializers/adapter/json.rb +2 -0
  34. data/lib/active_model_serializers/adapter/json_api/deserialization.rb +4 -2
  35. data/lib/active_model_serializers/adapter/json_api/error.rb +2 -0
  36. data/lib/active_model_serializers/adapter/json_api/jsonapi.rb +2 -0
  37. data/lib/active_model_serializers/adapter/json_api/link.rb +3 -1
  38. data/lib/active_model_serializers/adapter/json_api/meta.rb +2 -0
  39. data/lib/active_model_serializers/adapter/json_api/pagination_links.rb +49 -21
  40. data/lib/active_model_serializers/adapter/json_api/relationship.rb +77 -23
  41. data/lib/active_model_serializers/adapter/json_api/resource_identifier.rb +41 -10
  42. data/lib/active_model_serializers/adapter/json_api.rb +84 -65
  43. data/lib/active_model_serializers/adapter/null.rb +2 -0
  44. data/lib/active_model_serializers/adapter.rb +9 -1
  45. data/lib/active_model_serializers/callbacks.rb +2 -0
  46. data/lib/active_model_serializers/deprecate.rb +3 -2
  47. data/lib/active_model_serializers/deserialization.rb +4 -0
  48. data/lib/active_model_serializers/json_pointer.rb +2 -0
  49. data/lib/active_model_serializers/logging.rb +2 -0
  50. data/lib/active_model_serializers/lookup_chain.rb +82 -0
  51. data/lib/active_model_serializers/model/caching.rb +25 -0
  52. data/lib/active_model_serializers/model.rb +111 -28
  53. data/lib/active_model_serializers/railtie.rb +7 -1
  54. data/lib/active_model_serializers/register_jsonapi_renderer.rb +46 -31
  55. data/lib/active_model_serializers/serializable_resource.rb +10 -7
  56. data/lib/active_model_serializers/serialization_context.rb +12 -3
  57. data/lib/active_model_serializers/test/schema.rb +4 -2
  58. data/lib/active_model_serializers/test/serializer.rb +2 -0
  59. data/lib/active_model_serializers/test.rb +2 -0
  60. data/lib/active_model_serializers.rb +35 -10
  61. data/lib/generators/rails/resource_override.rb +3 -1
  62. data/lib/generators/rails/serializer_generator.rb +6 -4
  63. data/lib/grape/active_model_serializers.rb +9 -5
  64. data/lib/grape/formatters/active_model_serializers.rb +21 -2
  65. data/lib/grape/helpers/active_model_serializers.rb +3 -0
  66. data/lib/tasks/rubocop.rake +55 -0
  67. metadata +110 -276
  68. data/.github/ISSUE_TEMPLATE.md +0 -29
  69. data/.github/PULL_REQUEST_TEMPLATE.md +0 -15
  70. data/.gitignore +0 -35
  71. data/.rubocop.yml +0 -104
  72. data/.rubocop_todo.yml +0 -167
  73. data/.simplecov +0 -110
  74. data/.travis.yml +0 -43
  75. data/CONTRIBUTING.md +0 -105
  76. data/Gemfile +0 -53
  77. data/Rakefile +0 -103
  78. data/active_model_serializers.gemspec +0 -66
  79. data/appveyor.yml +0 -24
  80. data/bin/bench +0 -171
  81. data/bin/bench_regression +0 -316
  82. data/bin/serve_benchmark +0 -39
  83. data/docs/ARCHITECTURE.md +0 -126
  84. data/docs/README.md +0 -40
  85. data/docs/STYLE.md +0 -58
  86. data/docs/general/adapters.md +0 -245
  87. data/docs/general/caching.md +0 -52
  88. data/docs/general/configuration_options.md +0 -100
  89. data/docs/general/deserialization.md +0 -100
  90. data/docs/general/getting_started.md +0 -133
  91. data/docs/general/instrumentation.md +0 -40
  92. data/docs/general/key_transforms.md +0 -40
  93. data/docs/general/logging.md +0 -14
  94. data/docs/general/rendering.md +0 -255
  95. data/docs/general/serializers.md +0 -372
  96. data/docs/how-open-source-maintained.jpg +0 -0
  97. data/docs/howto/add_pagination_links.md +0 -139
  98. data/docs/howto/add_root_key.md +0 -51
  99. data/docs/howto/outside_controller_use.md +0 -58
  100. data/docs/howto/passing_arbitrary_options.md +0 -27
  101. data/docs/howto/serialize_poro.md +0 -32
  102. data/docs/howto/test.md +0 -152
  103. data/docs/integrations/ember-and-json-api.md +0 -112
  104. data/docs/integrations/grape.md +0 -19
  105. data/docs/jsonapi/errors.md +0 -56
  106. data/docs/jsonapi/schema/schema.json +0 -366
  107. data/docs/jsonapi/schema.md +0 -151
  108. data/docs/rfcs/0000-namespace.md +0 -106
  109. data/docs/rfcs/template.md +0 -15
  110. data/lib/active_model/serializer/associations.rb +0 -100
  111. data/lib/active_model/serializer/attributes.rb +0 -82
  112. data/lib/active_model/serializer/collection_reflection.rb +0 -7
  113. data/lib/active_model/serializer/configuration.rb +0 -35
  114. data/lib/active_model/serializer/include_tree.rb +0 -111
  115. data/lib/active_model/serializer/links.rb +0 -35
  116. data/lib/active_model/serializer/meta.rb +0 -29
  117. data/lib/active_model/serializer/singular_reflection.rb +0 -7
  118. data/lib/active_model/serializer/type.rb +0 -25
  119. data/lib/active_model_serializers/key_transform.rb +0 -70
  120. data/test/action_controller/adapter_selector_test.rb +0 -53
  121. data/test/action_controller/explicit_serializer_test.rb +0 -134
  122. data/test/action_controller/json/include_test.rb +0 -167
  123. data/test/action_controller/json_api/deserialization_test.rb +0 -112
  124. data/test/action_controller/json_api/errors_test.rb +0 -41
  125. data/test/action_controller/json_api/linked_test.rb +0 -197
  126. data/test/action_controller/json_api/pagination_test.rb +0 -116
  127. data/test/action_controller/json_api/transform_test.rb +0 -181
  128. data/test/action_controller/serialization_scope_name_test.rb +0 -229
  129. data/test/action_controller/serialization_test.rb +0 -469
  130. data/test/active_model_serializers/adapter_for_test.rb +0 -208
  131. data/test/active_model_serializers/json_pointer_test.rb +0 -20
  132. data/test/active_model_serializers/key_transform_test.rb +0 -263
  133. data/test/active_model_serializers/logging_test.rb +0 -77
  134. data/test/active_model_serializers/model_test.rb +0 -9
  135. data/test/active_model_serializers/railtie_test_isolated.rb +0 -63
  136. data/test/active_model_serializers/serialization_context_test_isolated.rb +0 -58
  137. data/test/active_model_serializers/test/schema_test.rb +0 -130
  138. data/test/active_model_serializers/test/serializer_test.rb +0 -62
  139. data/test/active_record_test.rb +0 -9
  140. data/test/adapter/deprecation_test.rb +0 -100
  141. data/test/adapter/json/belongs_to_test.rb +0 -45
  142. data/test/adapter/json/collection_test.rb +0 -90
  143. data/test/adapter/json/has_many_test.rb +0 -45
  144. data/test/adapter/json/transform_test.rb +0 -93
  145. data/test/adapter/json_api/belongs_to_test.rb +0 -155
  146. data/test/adapter/json_api/collection_test.rb +0 -95
  147. data/test/adapter/json_api/errors_test.rb +0 -78
  148. data/test/adapter/json_api/fields_test.rb +0 -87
  149. data/test/adapter/json_api/has_many_embed_ids_test.rb +0 -43
  150. data/test/adapter/json_api/has_many_explicit_serializer_test.rb +0 -96
  151. data/test/adapter/json_api/has_many_test.rb +0 -144
  152. data/test/adapter/json_api/has_one_test.rb +0 -80
  153. data/test/adapter/json_api/json_api_test.rb +0 -35
  154. data/test/adapter/json_api/linked_test.rb +0 -392
  155. data/test/adapter/json_api/links_test.rb +0 -93
  156. data/test/adapter/json_api/pagination_links_test.rb +0 -166
  157. data/test/adapter/json_api/parse_test.rb +0 -137
  158. data/test/adapter/json_api/relationship_test.rb +0 -161
  159. data/test/adapter/json_api/relationships_test.rb +0 -199
  160. data/test/adapter/json_api/resource_identifier_test.rb +0 -85
  161. data/test/adapter/json_api/resource_meta_test.rb +0 -100
  162. data/test/adapter/json_api/toplevel_jsonapi_test.rb +0 -82
  163. data/test/adapter/json_api/transform_test.rb +0 -502
  164. data/test/adapter/json_api/type_test.rb +0 -61
  165. data/test/adapter/json_test.rb +0 -45
  166. data/test/adapter/null_test.rb +0 -23
  167. data/test/adapter/polymorphic_test.rb +0 -171
  168. data/test/adapter_test.rb +0 -67
  169. data/test/array_serializer_test.rb +0 -22
  170. data/test/benchmark/app.rb +0 -65
  171. data/test/benchmark/benchmarking_support.rb +0 -67
  172. data/test/benchmark/bm_caching.rb +0 -119
  173. data/test/benchmark/bm_transform.rb +0 -34
  174. data/test/benchmark/config.ru +0 -3
  175. data/test/benchmark/controllers.rb +0 -84
  176. data/test/benchmark/fixtures.rb +0 -219
  177. data/test/cache_test.rb +0 -485
  178. data/test/collection_serializer_test.rb +0 -110
  179. data/test/fixtures/active_record.rb +0 -78
  180. data/test/fixtures/poro.rb +0 -282
  181. data/test/generators/scaffold_controller_generator_test.rb +0 -24
  182. data/test/generators/serializer_generator_test.rb +0 -57
  183. data/test/grape_test.rb +0 -82
  184. data/test/include_tree/from_include_args_test.rb +0 -26
  185. data/test/include_tree/from_string_test.rb +0 -94
  186. data/test/include_tree/include_args_to_hash_test.rb +0 -64
  187. data/test/lint_test.rb +0 -49
  188. data/test/logger_test.rb +0 -18
  189. data/test/poro_test.rb +0 -9
  190. data/test/serializable_resource_test.rb +0 -83
  191. data/test/serializers/association_macros_test.rb +0 -36
  192. data/test/serializers/associations_test.rb +0 -295
  193. data/test/serializers/attribute_test.rb +0 -151
  194. data/test/serializers/attributes_test.rb +0 -52
  195. data/test/serializers/caching_configuration_test_isolated.rb +0 -170
  196. data/test/serializers/configuration_test.rb +0 -32
  197. data/test/serializers/fieldset_test.rb +0 -14
  198. data/test/serializers/meta_test.rb +0 -196
  199. data/test/serializers/options_test.rb +0 -21
  200. data/test/serializers/read_attribute_for_serialization_test.rb +0 -79
  201. data/test/serializers/root_test.rb +0 -21
  202. data/test/serializers/serialization_test.rb +0 -55
  203. data/test/serializers/serializer_for_test.rb +0 -134
  204. data/test/support/custom_schemas/active_model_serializers/test/schema_test/my/index.json +0 -6
  205. data/test/support/isolated_unit.rb +0 -79
  206. data/test/support/rails5_shims.rb +0 -47
  207. data/test/support/rails_app.rb +0 -45
  208. data/test/support/schemas/active_model_serializers/test/schema_test/my/index.json +0 -6
  209. data/test/support/schemas/active_model_serializers/test/schema_test/my/show.json +0 -6
  210. data/test/support/schemas/custom/show.json +0 -7
  211. data/test/support/schemas/hyper_schema.json +0 -93
  212. data/test/support/schemas/render_using_json_api.json +0 -43
  213. data/test/support/schemas/simple_json_pointers.json +0 -10
  214. data/test/support/serialization_testing.rb +0 -53
  215. data/test/test_helper.rb +0 -57
data/docs/ARCHITECTURE.md DELETED
@@ -1,126 +0,0 @@
1
- [Back to Guides](README.md)
2
-
3
- This document focuses on architecture the 0.10.x version of ActiveModelSerializers. If you are interested in the architecture of the 0.8 or 0.9 versions,
4
- please refer to the [0.8 README](https://github.com/rails-api/active_model_serializers/blob/0-8-stable/README.md) or
5
- [0.9 README](https://github.com/rails-api/active_model_serializers/blob/0-9-stable/README.md).
6
-
7
- The original design is also available [here](https://github.com/rails-api/active_model_serializers/blob/d72b66d4c5355b0ff0a75a04895fcc4ea5b0c65e/README.textile).
8
-
9
- # ARCHITECTURE
10
-
11
- An **`ActiveModel::Serializer`** wraps a [serializable resource](https://github.com/rails/rails/blob/4-2-stable/activemodel/lib/active_model/serialization.rb)
12
- and exposes an `attributes` method, among a few others.
13
- It allows you to specify which attributes and associations should be represented in the serializatation of the resource.
14
- It requires an adapter to transform its attributes into a JSON document; it cannot be serialized itself.
15
- It may be useful to think of it as a
16
- [presenter](http://blog.steveklabnik.com/posts/2011-09-09-better-ruby-presenters).
17
-
18
- The **`ActiveModel::ArraySerializer`** represent a collection of resources as serializers
19
- and, if there is no serializer, primitives.
20
-
21
- The **`ActiveModel::Adapter`** describes the structure of the JSON document generated from a
22
- serializer. For example, the `Attributes` example represents each serializer as its
23
- unmodified attributes. The `JsonApi` adapter represents the serializer as a [JSON
24
- API](http://jsonapi.org/) document.
25
-
26
- The **`ActiveModelSerializers::SerializableResource`** acts to coordinate the serializer(s) and adapter
27
- to an object that responds to `to_json`, and `as_json`. It is used in the controller to
28
- encapsulate the serialization resource when rendered. However, it can also be used on its own
29
- to serialize a resource outside of a controller, as well.
30
-
31
- ## Primitive handling
32
-
33
- Definitions: A primitive is usually a String or Array. There is no serializer
34
- defined for them; they will be serialized when the resource is converted to JSON (`as_json` or
35
- `to_json`). (The below also applies for any object with no serializer.)
36
-
37
- ActiveModelSerializers doesn't handle primitives passed to `render json:` at all.
38
-
39
- However, when a primitive value is an attribute or in a collection,
40
- it is not modified.
41
-
42
- Internally, if no serializer can be found in the controller, the resource is not decorated by
43
- ActiveModelSerializers.
44
-
45
- If the collection serializer (ArraySerializer) cannot
46
- identify a serializer for a resource in its collection, it raises [`NoSerializerError`](https://github.com/rails-api/active_model_serializers/issues/1191#issuecomment-142327128)
47
- which is rescued in `ActiveModel::Serializer::Reflection#build_association` which sets
48
- the association value directly:
49
-
50
- ```ruby
51
- reflection_options[:virtual_value] = association_value.try(:as_json) || association_value
52
- ```
53
-
54
- (which is called by the adapter as `serializer.associations(*)`.)
55
-
56
- ## How options are parsed
57
-
58
- High-level overview:
59
-
60
- - For a collection
61
- - `:serializer` specifies the collection serializer and
62
- - `:each_serializer` specifies the serializer for each resource in the collection.
63
- - For a single resource, the `:serializer` option is the resource serializer.
64
- - Options are partitioned in serializer options and adapter options. Keys for adapter options are specified by
65
- [`ADAPTER_OPTION_KEYS`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/serializable_resource.rb#L5).
66
- The remaining options are serializer options.
67
-
68
- Details:
69
-
70
- 1. **ActionController::Serialization**
71
- 1. `serializable_resource = ActiveModelSerializers::SerializableResource.new(resource, options)`
72
- 1. `options` are partitioned into `adapter_opts` and everything else (`serializer_opts`).
73
- The `adapter_opts` keys are defined in `ActiveModelSerializers::SerializableResource::ADAPTER_OPTION_KEYS`.
74
- 1. **ActiveModelSerializers::SerializableResource**
75
- 1. `if serializable_resource.serializer?` (there is a serializer for the resource, and an adapter is used.)
76
- - Where `serializer?` is `use_adapter? && !!(serializer)`
77
- - Where `use_adapter?`: 'True when no explicit adapter given, or explicit value is truthy (non-nil);
78
- False when explicit adapter is falsy (nil or false)'
79
- - Where `serializer`:
80
- 1. from explicit `:serializer` option, else
81
- 2. implicitly from resource `ActiveModel::Serializer.serializer_for(resource)`
82
- 1. A side-effect of checking `serializer` is:
83
- - The `:serializer` option is removed from the serializer_opts hash
84
- - If the `:each_serializer` option is present, it is removed from the serializer_opts hash and set as the `:serializer` option
85
- 1. The serializer and adapter are created as
86
- 1. `serializer_instance = serializer.new(resource, serializer_opts)`
87
- 2. `adapter_instance = ActiveModel::Serializer::Adapter.create(serializer_instance, adapter_opts)`
88
- 1. **ActiveModel::Serializer::ArraySerializer#new**
89
- 1. If the `serializer_instance` was a `ArraySerializer` and the `:serializer` serializer_opts
90
- is present, then [that serializer is passed into each resource](https://github.com/rails-api/active_model_serializers/blob/a54d237e2828fe6bab1ea5dfe6360d4ecc8214cd/lib/active_model/serializer/array_serializer.rb#L14-L16).
91
- 1. **ActiveModel::Serializer#attributes** is used by the adapter to get the attributes for
92
- resource as defined by the serializer.
93
-
94
- ## What does a 'serializable resource' look like?
95
-
96
- - An `ActiveRecord::Base` object.
97
- - Any Ruby object that passes the
98
- [Lint](http://www.rubydoc.info/github/rails-api/active_model_serializers/ActiveModel/Serializer/Lint/Tests)
99
- [code](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer/lint.rb).
100
-
101
- ActiveModelSerializers provides a
102
- [`ActiveModelSerializers::Model`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/model.rb),
103
- which is a simple serializable PORO (Plain-Old Ruby Object).
104
-
105
- ActiveModelSerializers::Model may be used either as a template, or in production code.
106
-
107
- ```ruby
108
- class MyModel < ActiveModelSerializers::Model
109
- attr_accessor :id, :name, :level
110
- end
111
- ```
112
-
113
- The default serializer for `MyModel` would be `MyModelSerializer` whether MyModel is an
114
- ActiveRecord::Base object or not.
115
-
116
- Outside of the controller the rules are **exactly** the same as for records. For example:
117
-
118
- ```ruby
119
- render json: MyModel.new(level: 'awesome'), adapter: :json
120
- ```
121
-
122
- would be serialized the same as
123
-
124
- ```ruby
125
- ActiveModelSerializers::SerializableResource.new(MyModel.new(level: 'awesome'), adapter: :json).as_json
126
- ```
data/docs/README.md DELETED
@@ -1,40 +0,0 @@
1
- # Docs - ActiveModel::Serializer 0.10.x
2
-
3
- This is the documentation of ActiveModelSerializers, it's focused on the **0.10.x version.**
4
-
5
- -----
6
-
7
- ## General
8
-
9
- - [Getting Started](general/getting_started.md)
10
- - [Configuration Options](general/configuration_options.md)
11
- - [Serializers](general/serializers.md)
12
- - [Adapters](general/adapters.md)
13
- - [Rendering](general/rendering.md)
14
- - [Caching](general/caching.md)
15
- - [Logging](general/logging.md)
16
- - [Deserialization](general/deserialization.md)
17
- - [Instrumentation](general/instrumentation.md)
18
- - JSON API
19
- - [Schema](jsonapi/schema.md)
20
- - [Errors](jsonapi/errors.md)
21
- - [ARCHITECTURE](ARCHITECTURE.md)
22
-
23
- ## How to
24
-
25
- - [How to add root key](howto/add_root_key.md)
26
- - [How to add pagination links](howto/add_pagination_links.md)
27
- - [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
28
- - [Testing ActiveModelSerializers](howto/test.md)
29
- - [Passing Arbitrary Options](howto/passing_arbitrary_options.md)
30
- - [How to serialize a Plain-Old Ruby Object (PORO)](howto/serialize_poro.md)
31
-
32
- ## Integrations
33
-
34
- | Integration | Supported ActiveModelSerializers versions | Gem name and/or link
35
- |----|-----|----
36
- | Ember.js | 0.9.x | [active-model-adapter](https://github.com/ember-data/active-model-adapter)
37
- | Ember.js | 0.10.x + | [docs/integrations/ember-and-json-api.md](integrations/ember-and-json-api.md)
38
- | Grape | 0.10.x + | [docs/integrations/grape.md](integrations/grape.md) |
39
- | Grape | 0.9.x | https://github.com/jrhe/grape-active_model_serializers/ |
40
- | Sinatra | 0.9.x | https://github.com/SauloSilva/sinatra-active-model-serializers/
data/docs/STYLE.md DELETED
@@ -1,58 +0,0 @@
1
- # STYLE
2
-
3
- ## Code and comments
4
-
5
- - We are actively working to identify tasks under the label [**Good for New
6
- Contributors**](https://github.com/rails-api/active_model_serializers/labels/Good%20for%20New%20Contributors).
7
- - [Changelog
8
- Missing](https://github.com/rails-api/active_model_serializers/issues?q=label%3A%22Changelog+Missing%22+is%3Aclosed) is
9
- an easy way to help out.
10
-
11
- - [Fix a bug](https://github.com/rails-api/active_model_serializers/labels/Ready%20for%20PR).
12
- - Ready for PR - A well defined bug, needs someone to PR a fix.
13
- - Bug - Anything that is broken.
14
- - Regression - A bug that did not exist in previous versions and isn't a new feature (applied in tandem with Bug).
15
- - Performance - A performance related issue. We could track this as a bug, but usually these would have slightly lower priority than standard bugs.
16
-
17
- - [Develop new features](https://github.com/rails-api/active_model_serializers/labels/Feature).
18
-
19
- - [Improve code quality](https://codeclimate.com/github/rails-api/active_model_serializers/code?sort=smell_count&sort_direction=desc).
20
-
21
- - [Improve amount of code exercised by tests](https://codeclimate.com/github/rails-api/active_model_serializers/coverage?sort=covered_percent&sort_direction=asc).
22
-
23
- - [Fix RuboCop (Style) TODOS](https://github.com/rails-api/active_model_serializers/blob/master/.rubocop_todo.yml).
24
- - Delete and offsense, run `rake rubocop` (or possibly `rake rubocop:auto_correct`),
25
- and [submit a PR](CONTRIBUTING.md#submitting-a-pull-request-pr).
26
-
27
- - We are also encouraging comments to substantial changes (larger than bugfixes and simple features) under an
28
- "RFC" (Request for Comments) process before we start active development.
29
- Look for the [**RFC**](https://github.com/rails-api/active_model_serializers/labels/RFC) label.
30
-
31
-
32
- ## Pull requests
33
-
34
- - If the tests pass and the pull request looks good, a maintainer will merge it.
35
- - If the pull request needs to be changed,
36
- - you can change it by updating the branch you generated the pull request from
37
- - either by adding more commits, or
38
- - by force pushing to it
39
- - A maintainer can make any changes themselves and manually merge the code in.
40
-
41
- ## Commit messages
42
-
43
- - [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
44
- - [http://stopwritingramblingcommitmessages.com/](http://stopwritingramblingcommitmessages.com/)
45
- - [ThoughtBot style guide](https://github.com/thoughtbot/guides/tree/master/style#git)
46
-
47
- #### About Pull Requests (PR's)
48
-
49
- - [Using Pull Requests](https://help.github.com/articles/using-pull-requests)
50
- - [Github pull requests made easy](http://www.element84.com/github-pull-requests-made-easy.html)
51
- - [Exercism Git Workflow](http://help.exercism.io/git-workflow.html).
52
- - [Level up your Git](http://rakeroutes.com/blog/deliberate-git/)
53
- - [All Your Open Source Code Are Belong To Us](http://www.benjaminfleischer.com/2013/07/30/all-your-open-source-code-are-belong-to-us/)
54
-
55
- ## Issue Labeling
56
-
57
- ActiveModelSerializers uses a subset of [StandardIssueLabels](https://github.com/wagenet/StandardIssueLabels) for Github Issues. You can [see our labels here](https://github.com/rails-api/active_model_serializers/labels).
58
-
@@ -1,245 +0,0 @@
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 = ActiveModelSerializers::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
- ##### Example output
47
-
48
- ```json
49
- {
50
- "title": "Title 1",
51
- "body": "Body 1",
52
- "publish_at": "2020-03-16T03:55:25.291Z",
53
- "author": {
54
- "first_name": "Bob",
55
- "last_name": "Jones"
56
- },
57
- "comments": [
58
- {
59
- "body": "cool"
60
- },
61
- {
62
- "body": "awesome"
63
- }
64
- ]
65
- }
66
- ```
67
-
68
- ### JSON
69
-
70
- The response document always with a root key.
71
-
72
- The root key **can't be overridden**, and will be derived from the resource being serialized.
73
-
74
- Doesn't follow any specific convention.
75
-
76
- ##### Example output
77
-
78
- ```json
79
- {
80
- "post": {
81
- "title": "Title 1",
82
- "body": "Body 1",
83
- "publish_at": "2020-03-16T03:55:25.291Z",
84
- "author": {
85
- "first_name": "Bob",
86
- "last_name": "Jones"
87
- },
88
- "comments": [{
89
- "body": "cool"
90
- }, {
91
- "body": "awesome"
92
- }]
93
- }
94
- }
95
- ```
96
-
97
- ### JSON API
98
-
99
- This adapter follows **version 1.0** of the [format specified](../jsonapi/schema.md) in
100
- [jsonapi.org/format](http://jsonapi.org/format).
101
-
102
- ##### Example output
103
-
104
- ```json
105
- {
106
- "data": {
107
- "id": "1337",
108
- "type": "posts",
109
- "attributes": {
110
- "title": "Title 1",
111
- "body": "Body 1",
112
- "publish-at": "2020-03-16T03:55:25.291Z"
113
- },
114
- "relationships": {
115
- "author": {
116
- "data": {
117
- "id": "1",
118
- "type": "authors"
119
- }
120
- },
121
- "comments": {
122
- "data": [{
123
- "id": "7",
124
- "type": "comments"
125
- }, {
126
- "id": "12",
127
- "type": "comments"
128
- }]
129
- }
130
- },
131
- "links": {
132
- "post-authors": "https://example.com/post_authors"
133
- },
134
- "meta": {
135
- "rating": 5,
136
- "favorite-count": 10
137
- }
138
- }
139
- }
140
- ```
141
-
142
- #### Included
143
-
144
- It will include the associated resources in the `"included"` member
145
- when the resource names are included in the `include` option.
146
- Including nested associated resources is also supported.
147
-
148
- ```ruby
149
- render json: @posts, include: ['author', 'comments', 'comments.author']
150
- # or
151
- render json: @posts, include: 'author,comments,comments.author'
152
- ```
153
-
154
- In addition, two types of wildcards may be used:
155
-
156
- - `*` includes one level of associations.
157
- - `**` includes all recursively.
158
-
159
- These can be combined with other paths.
160
-
161
- ```ruby
162
- render json: @posts, include: '**' # or '*' for a single layer
163
- ```
164
-
165
- The format of the `include` option can be either:
166
-
167
- - a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes).
168
- - an Array of Symbols and Hashes.
169
- - a mix of both.
170
-
171
- The following would render posts and include:
172
-
173
- - the author
174
- - the author's comments, and
175
- - every resource referenced by the author's comments (recursively).
176
-
177
- It could be combined, like above, with other paths in any combination desired.
178
-
179
- ```ruby
180
- render json: @posts, include: 'author.comments.**'
181
- ```
182
-
183
- ##### Security Considerations
184
-
185
- Since the included options may come from the query params (i.e. user-controller):
186
-
187
- ```ruby
188
- render json: @posts, include: params[:include]
189
- ```
190
-
191
- The user could pass in `include=**`.
192
-
193
- We recommend filtering any user-supplied includes appropriately.
194
-
195
- ## Advanced adapter configuration
196
-
197
- ### Registering an adapter
198
-
199
- The default adapter can be configured, as above, to use any class given to it.
200
-
201
- An adapter may also be specified, e.g. when rendering, as a class or as a symbol.
202
- If a symbol, then the adapter must be, e.g. `:great_example`,
203
- `ActiveModelSerializers::Adapter::GreatExample`, or registered.
204
-
205
- There are two ways to register an adapter:
206
-
207
- 1) The simplest, is to subclass `ActiveModelSerializers::Adapter::Base`, e.g. the below will
208
- register the `Example::UsefulAdapter` as `"example/useful_adapter"`.
209
-
210
- ```ruby
211
- module Example
212
- class UsefulAdapter < ActiveModelSerializers::Adapter::Base
213
- end
214
- end
215
- ```
216
-
217
- You'll notice that the name it registers is the underscored namespace and class.
218
-
219
- Under the covers, when the `ActiveModelSerializers::Adapter::Base` is subclassed, it registers
220
- the subclass as `register("example/useful_adapter", Example::UsefulAdapter)`
221
-
222
- 2) Any class can be registered as an adapter by calling `register` directly on the
223
- `ActiveModelSerializers::Adapter` class. e.g., the below registers `MyAdapter` as
224
- `:special_adapter`.
225
-
226
- ```ruby
227
- class MyAdapter; end
228
- ActiveModelSerializers::Adapter.register(:special_adapter, MyAdapter)
229
- ```
230
-
231
- ### Looking up an adapter
232
-
233
- | Method | Return value |
234
- | :------------ |:---------------|
235
- | `ActiveModelSerializers::Adapter.adapter_map` | A Hash of all known adapters `{ adapter_name => adapter_class }` |
236
- | `ActiveModelSerializers::Adapter.adapters` | A (sorted) Array of all known `adapter_names` |
237
- | `ActiveModelSerializers::Adapter.lookup(name_or_klass)` | The `adapter_class`, else raises an `ActiveModelSerializers::Adapter::UnknownAdapter` error |
238
- | `ActiveModelSerializers::Adapter.adapter_class(adapter)` | Delegates to `ActiveModelSerializers::Adapter.lookup(adapter)` |
239
- | `ActiveModelSerializers::Adapter.configured_adapter` | A convenience method for `ActiveModelSerializers::Adapter.lookup(config.adapter)` |
240
-
241
- The registered adapter name is always a String, but may be looked up as a Symbol or String.
242
- Helpfully, the Symbol or String is underscored, so that `get(:my_adapter)` and `get("MyAdapter")`
243
- may both be used.
244
-
245
- For more information, see [the Adapter class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/adapter.rb)
@@ -1,52 +0,0 @@
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
- ```
@@ -1,100 +0,0 @@
1
- [Back to Guides](../README.md)
2
-
3
- # Configuration Options
4
-
5
- The following configuration options can be set on
6
- `ActiveModelSerializers.config`, preferably inside an initializer.
7
-
8
- ## General
9
-
10
- ##### adapter
11
-
12
- The [adapter](adapters.md) to use.
13
-
14
- Possible values:
15
-
16
- - `:attributes` (default)
17
- - `:json`
18
- - `:json_api`
19
-
20
- ##### serializer_lookup_enabled
21
-
22
- Enable automatic serializer lookup.
23
-
24
- Possible values:
25
-
26
- - `true` (default)
27
- - `false`
28
-
29
- When `false`, serializers must be explicitly specified.
30
-
31
- ##### key_transform
32
-
33
- The [key transform](key_transforms.md) to use.
34
-
35
-
36
- | Option | Result |
37
- |----|----|
38
- | `:camel` | ExampleKey |
39
- | `:camel_lower` | exampleKey |
40
- | `:dash` | example-key |
41
- | `:unaltered` | the original, unaltered key |
42
- | `:underscore` | example_key |
43
- | `nil` | use the adapter default |
44
-
45
- Each adapter has a default key transform configured:
46
-
47
- | Adapter | Default Key Transform |
48
- |----|----|
49
- | `Json` | `:unaltered` |
50
- | `JsonApi` | `:dash` |
51
-
52
- `config.key_transform` is a global override of the adapter default. Adapters
53
- still prefer the render option `:key_transform` over this setting.
54
-
55
-
56
- ## JSON API
57
-
58
-
59
- ##### jsonapi_resource_type
60
-
61
- Sets whether the [type](http://jsonapi.org/format/#document-resource-identifier-objects)
62
- of the resource should be `singularized` or `pluralized` when it is not
63
- [explicitly specified by the serializer](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/serializers.md#type)
64
-
65
- Possible values:
66
-
67
- - `:singular`
68
- - `:plural` (default)
69
-
70
- ##### jsonapi_include_toplevel_object
71
-
72
- Include a [top level jsonapi member](http://jsonapi.org/format/#document-jsonapi-object)
73
- in the response document.
74
-
75
- Possible values:
76
-
77
- - `true`
78
- - `false` (default)
79
-
80
- ##### jsonapi_version
81
-
82
- The latest version of the spec to which the API conforms.
83
-
84
- Default: `'1.0'`.
85
-
86
- *Used when `jsonapi_include_toplevel_object` is `true`*
87
-
88
- ##### jsonapi_toplevel_meta
89
-
90
- Optional top-level metadata. Not included if empty.
91
-
92
- Default: `{}`.
93
-
94
- *Used when `jsonapi_include_toplevel_object` is `true`*
95
-
96
-
97
- ## Hooks
98
-
99
- To run a hook when ActiveModelSerializers is loaded, use
100
- `ActiveSupport.on_load(:action_controller) do end`