ditkrg/active_model_serializers
4
0
Fork 0
mirror of https://github.com/ditkrg/active_model_serializers.git synced 2026-01-22 22:06:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

[0.10] add docs for include (#2081)

Browse Source 
* Add docs for `include` option in the adapter
This commit is contained in:
Timur 2017-03-28 13:14:50 +06:00 committed by Benjamin Fleischer
parent d24a7867b9
commit 1a5e66b933
2 changed files with 27 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -10,6 +10,8 @@ Fixes:
Misc: Misc:
- [#2081](https://github.com/rails-api/active_model_serializers/pull/2081) Documentation for `include` option in adapters. (@charlie-wasp)
### [v0.10.5 (2017-03-07)](https://github.com/rails-api/active_model_serializers/compare/v0.10.4...v0.10.5) ### [v0.10.5 (2017-03-07)](https://github.com/rails-api/active_model_serializers/compare/v0.10.4...v0.10.5)
Breaking changes: Breaking changes:

34
docs/general/adapters.md
View File

@ -141,18 +141,25 @@ This adapter follows **version 1.0** of the [format specified](../jsonapi/schema
} }
``` ```
#### Included ### Include option
It will include the associated resources in the `"included"` member Which [serializer associations](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/serializers.md#associations) are rendered can be specified using the `include` option. The option usage is consistent with [the include option in the JSON API spec](http://jsonapi.org/format/#fetching-includes), and is available in all adapters.
when the resource names are included in the `include` option.
Including nested associated resources is also supported.
Example of the usage:
```ruby ```ruby
render json: @posts, include: ['author', 'comments', 'comments.author'] render json: @posts, include: ['author', 'comments', 'comments.author']
# or # or
render json: @posts, include: 'author,comments,comments.author' render json: @posts, include: 'author,comments,comments.author'
``` ```
The format of the `include` option can be either:
- a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes).
- an Array of Symbols and Hashes.
- a mix of both.
An empty string or an empty array will prevent rendering of any associations.
In addition, two types of wildcards may be used: In addition, two types of wildcards may be used:
- `*` includes one level of associations. - `*` includes one level of associations.
@ -164,11 +171,6 @@ These can be combined with other paths.
render json: @posts, include: '**' # or '*' for a single layer render json: @posts, include: '**' # or '*' for a single layer
``` ```
The format of the `include` option can be either:
- a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes).
- an Array of Symbols and Hashes.
- a mix of both.
The following would render posts and include: The following would render posts and include:
@ -182,6 +184,20 @@ It could be combined, like above, with other paths in any combination desired.
render json: @posts, include: 'author.comments.**' render json: @posts, include: 'author.comments.**'
``` ```
**Note:** Wildcards are ActiveModelSerializers-specific, they are not part of the JSON API spec.
The default include for the JSON API adapter is no associations. The default for the JSON and Attributes adapters is all associations.
For the JSON API adapter associated resources will be gathered in the `"included"` member. For the JSON and Attributes
adapters associated resources will be rendered among the other attributes.
Only for the JSON API adapter you can specify, which attributes of associated resources will be rendered. This feature
is called [sparse fieldset](http://jsonapi.org/format/#fetching-sparse-fieldsets):
```ruby
render json: @posts, include: 'comments', fields: { comments: ['content', 'created_at'] }
```
##### Security Considerations ##### Security Considerations
Since the included options may come from the query params (i.e. user-controller): Since the included options may come from the query params (i.e. user-controller):