Merge pull request #1574 from remear/key-casing

Provide key transformation

docs/general/configuration_options.md

@@ -2,26 +2,95 @@
 
 # Configuration Options
 
-The following configuration options can be set on `ActiveModelSerializers.config`,
-preferably inside an initializer.
+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, :json, :json_api`. Default: `:attributes`.
-- `serializer_lookup_enabled`: When `false`, serializers must be explicitly specified. Default: `true`
+##### 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_transform.md) to use.
+
+Possible values:
+
+- `:camel` - ExampleKey
+- `:camel_lower` - exampleKey
+- `:dashed` - example-key
+- `:unaltered` - the original, unaltered key
+- `nil` - use the adapter default
+
+Each adapter has a default key transform configured:
+
+- `Json` - `:unaltered`
+- `JsonApi` - `:dashed`
+
+`config.key_transform` is a global override of the adapter default. Adapters
+still prefer the render option `:key_transform` over this setting.
+
 
 ## JSON API
 
-- `jsonapi_resource_type`: Whether the `type` attributes of resources should be singular or plural. Possible values: `:singular, :plural`. Default: `:plural`.
-- `jsonapi_include_toplevel_object`: Whether to include a [top level JSON API member](http://jsonapi.org/format/#document-jsonapi-object)
-   in the response document.
-   Default: `false`.
-- Used when `jsonapi_include_toplevel_object` is `true`:
-  - `jsonapi_version`: The latest version of the spec the API conforms to.
-    Default: `'1.0'`.
-  - `jsonapi_toplevel_meta`: Optional metadata. Not included if empty.
-    Default: `{}`.
+
+##### 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_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`
+To run a hook when ActiveModelSerializers is loaded, use
+`ActiveSupport.on_load(:action_controller) do end`

docs/general/key_transform.md

@@ -0,0 +1,34 @@
+[Back to Guides](../README.md)
+
+# Key Transforms
+
+Key transforms modify the keys in serialized responses.
+
+Provided key transforms:
+
+- `:camel` - ExampleKey
+- `:camel_lower` - exampleKey
+- `:dashed` - example-key
+- `:unaltered` - the original, unaltered key
+- `nil` - use the adapter default
+
+Key translation precedence is as follows:
+
+##### SerializableResource option
+
+`key_transform` is provided as an option via render.
+
+```render json: posts, each_serializer: PostSerializer, key_transform: :camel_lower```
+
+##### Configuration option
+
+`key_transform` is set in `ActiveModelSerializers.config.key_transform`.
+
+```ActiveModelSerializers.config.key_transform = :camel_lower```
+
+##### Adapter default
+
+Each adapter has a default key transform configured:
+
+- `Json` - `:unaltered`
+- `JsonApi` - `:dashed`

docs/general/rendering.md

@@ -79,6 +79,12 @@ PR please :)
 
 PR please :)
 
+#### key_transform
+
+```render json: posts, each_serializer: PostSerializer, key_transform: :camel_lower```
+
+See [Key Transforms](key_transforms.md) for more informaiton.
+
 #### meta
 
 A `meta` member can be used to include non-standard meta-information. `meta` can