diff --git a/CHANGELOG.md b/CHANGELOG.md index a40d777b0..99080b551 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ Fixes: Misc: - [#1734](https://github.com/rails-api/active_model_serializers/pull/1734) Adds documentation for conditional attribute (@lambda2) - [#1685](https://github.com/rails-api/active_model_serializers/pull/1685) Replace `IncludeTree` with `IncludeDirective` from the jsonapi gem. +- [#1808](https://github.com/rails-api/active_model_serializers/pull/1808) Adds documentation for `fields` option. (@luizkowalski) ### [v0.10.0 (2016-05-17)](https://github.com/rails-api/active_model_serializers/compare/4a2d9853ba7...v0.10.0) diff --git a/docs/general/fields.md b/docs/general/fields.md new file mode 100644 index 000000000..4078977bb --- /dev/null +++ b/docs/general/fields.md @@ -0,0 +1,31 @@ +[Back to Guides](../README.md) + +# Fields + +If for any reason, you need to restrict the fields returned, you should use `fields` option. + +For example, if you have a serializer like this + +```ruby +class UserSerializer < ActiveModel::Serializer + attributes :access_token, :first_name, :last_name +end +``` + +and in a specific controller, you want to return `access_token` only, `fields` will help you: + +```ruby +class AnonymousController < ApplicationController + def create + render json: User.create(activation_state: 'anonymous'), fields: [:access_token], status: 201 + end +end +``` + +Note that this is only valid for the `json` adapter. For the `json_api` adapter, you would use + +```ruby +render json: @user, fields: { users: [:access_token] } +``` + +Where `users` is the JSONAPI type. diff --git a/docs/general/rendering.md b/docs/general/rendering.md index 35c84958a..27f945eb7 100644 --- a/docs/general/rendering.md +++ b/docs/general/rendering.md @@ -73,7 +73,21 @@ See [ARCHITECTURE](../ARCHITECTURE.md) for more information. #### fields -PR please :) +If you are using `json` adapter +```ruby +render json: @user, fields: [:access_token] +``` + +or if you your adapter is `json_api`, then you should change as below + +```ruby +render json: @user, fields: { users: [:access_token] } +``` + +where `users` is your JSONAPI type. + + +See [Fields](fields.md) for more information. #### adapter @@ -83,7 +97,7 @@ PR please :) ```render json: posts, each_serializer: PostSerializer, key_transform: :camel_lower``` -See [Key Transforms](key_transforms.md) for more informaiton. +See [Key Transforms](key_transforms.md) for more information. #### meta