mirror of
https://github.com/ditkrg/active_model_serializers.git
synced 2026-01-23 14:29:31 +00:00
170 lines
4.3 KiB
Markdown
170 lines
4.3 KiB
Markdown
[Back to Guides](../README.md)
|
|
|
|
# Configuration Options
|
|
|
|
The following configuration options can be set on
|
|
`ActiveModelSerializers.config`, preferably inside an initializer.
|
|
|
|
## General
|
|
|
|
##### adapter
|
|
|
|
The [adapter](adapters.md) to use.
|
|
|
|
Possible values:
|
|
|
|
- `:attributes` (default)
|
|
- `:json`
|
|
- `:json_api`
|
|
|
|
##### serializer_lookup_enabled
|
|
|
|
Enable automatic serializer lookup.
|
|
|
|
Possible values:
|
|
|
|
- `true` (default)
|
|
- `false`
|
|
|
|
When `false`, serializers must be explicitly specified.
|
|
|
|
##### key_transform
|
|
|
|
The [key transform](key_transforms.md) to use.
|
|
|
|
|
|
| Option | Result |
|
|
|----|----|
|
|
| `:camel` | ExampleKey |
|
|
| `:camel_lower` | exampleKey |
|
|
| `:dash` | example-key |
|
|
| `:unaltered` | the original, unaltered key |
|
|
| `:underscore` | example_key |
|
|
| `nil` | use the adapter default |
|
|
|
|
Each adapter has a default key transform configured:
|
|
|
|
| Adapter | Default Key Transform |
|
|
|----|----|
|
|
| `Attributes` | `:unaltered` |
|
|
| `Json` | `:unaltered` |
|
|
| `JsonApi` | `:dash` |
|
|
|
|
`config.key_transform` is a global override of the adapter default. Adapters
|
|
still prefer the render option `:key_transform` over this setting.
|
|
|
|
*NOTE: Key transforms can be expensive operations. If key transforms are unnecessary for the
|
|
application, setting `config.key_transform` to `:unaltered` will provide a performance boost.*
|
|
|
|
##### default_includes
|
|
What relationships to serialize by default. Default: `'*'`, which includes one level of related
|
|
objects. See [includes](adapters.md#included) for more info.
|
|
|
|
|
|
##### serializer_lookup_chain
|
|
|
|
Configures how serializers are searched for. By default, the lookup chain is
|
|
|
|
```ruby
|
|
ActiveModelSerializers::LookupChain::DEFAULT
|
|
```
|
|
|
|
which is shorthand for
|
|
|
|
```ruby
|
|
[
|
|
ActiveModelSerializers::LookupChain::BY_PARENT_SERIALIZER,
|
|
ActiveModelSerializers::LookupChain::BY_NAMESPACE,
|
|
ActiveModelSerializers::LookupChain::BY_RESOURCE_NAMESPACE,
|
|
ActiveModelSerializers::LookupChain::BY_RESOURCE
|
|
]
|
|
```
|
|
|
|
Each of the array entries represent a proc. A serializer lookup proc will be yielded 3 arguments. `resource_class`, `serializer_class`, and `namespace`.
|
|
|
|
Note that:
|
|
- `resource_class` is the class of the resource being rendered
|
|
- by default `serializer_class` is `ActiveModel::Serializer`
|
|
- for association lookup it's the "parent" serializer
|
|
- `namespace` correspond to either the controller namespace or the [optionally] specified [namespace render option](./rendering.md#namespace)
|
|
|
|
An example config could be:
|
|
|
|
```ruby
|
|
ActiveModelSerializers.config.serializer_lookup_chain = [
|
|
lambda do |resource_class, serializer_class, namespace|
|
|
"API::#{namespace}::#{resource_class}"
|
|
end
|
|
]
|
|
```
|
|
|
|
If you simply want to add to the existing lookup_chain. Use `unshift`.
|
|
|
|
```ruby
|
|
ActiveModelSerializers.config.serializer_lookup_chain.unshift(
|
|
lambda do |resource_class, serializer_class, namespace|
|
|
# ...
|
|
end
|
|
)
|
|
```
|
|
|
|
See [lookup_chain.rb](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/lookup_chain.rb) for further explanations and examples.
|
|
|
|
## JSON API
|
|
|
|
##### jsonapi_resource_type
|
|
|
|
Sets whether the [type](http://jsonapi.org/format/#document-resource-identifier-objects)
|
|
of the resource should be `singularized` or `pluralized` when it is not
|
|
[explicitly specified by the serializer](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/serializers.md#type)
|
|
|
|
Possible values:
|
|
|
|
- `:singular`
|
|
- `:plural` (default)
|
|
|
|
##### jsonapi_namespace_separator
|
|
|
|
Sets separator string for namespaced models to render `type` attribute.
|
|
|
|
|
|
| Separator | Example: Admin::User |
|
|
|----|----|
|
|
| `'-'` (default) | 'admin-users'
|
|
| `'--'` (recommended) | 'admin--users'
|
|
|
|
See [Recommendation for dasherizing (kebab-case-ing) namespaced object, such as `Admin::User`](https://github.com/json-api/json-api/issues/850)
|
|
for more discussion.
|
|
|
|
##### jsonapi_include_toplevel_object
|
|
|
|
Include a [top level jsonapi member](http://jsonapi.org/format/#document-jsonapi-object)
|
|
in the response document.
|
|
|
|
Possible values:
|
|
|
|
- `true`
|
|
- `false` (default)
|
|
|
|
##### jsonapi_version
|
|
|
|
The latest version of the spec to which the API conforms.
|
|
|
|
Default: `'1.0'`.
|
|
|
|
*Used when `jsonapi_include_toplevel_object` is `true`*
|
|
|
|
##### jsonapi_toplevel_meta
|
|
|
|
Optional top-level metadata. Not included if empty.
|
|
|
|
Default: `{}`.
|
|
|
|
*Used when `jsonapi_include_toplevel_object` is `true`*
|
|
|
|
|
|
## Hooks
|
|
|
|
To run a hook when ActiveModelSerializers is loaded, use
|
|
`ActiveSupport.on_load(:action_controller) do end`
|