Added docs for the fields

Added md file

Changelog

Better phrases

Added info for other adapters

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)
 

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` and `attributes` adapter. For the `json_api` adapter, you would use
+
+```ruby
+render json: @user, fields: { users: [:access_token] }
+```
+
+Where `users` is the JSONAPI type.

docs/general/rendering.md

@@ -73,7 +73,21 @@ See [ARCHITECTURE](../ARCHITECTURE.md) for more information.
 
 #### fields
 
-PR please :)
+If you are using `json` or `attributes` 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