[0.10] add docs for include #2081
Conversation
|
@charlie-wasp, thanks for your PR! By analyzing the history of the files in this pull request, we identified @bf4, @beauby and @remear to be potential reviewers. |
charlie-wasp
force-pushed
the
1243-add-docs-for-include
branch
from
8aa2b42 to
30c509d
Compare
charlie-wasp
force-pushed
the
1243-add-docs-for-include
branch
from
30c509d to
4f0b60d
Compare
docs/general/adapters.md
Outdated
|
|
||
| ```ruby | ||
| render json: @posts, include: ['author', 'comments', 'comments.author'] | ||
| # or | ||
| render json: @posts, include: 'author,comments,comments.author' | ||
| ``` | ||
| **Note:** Serializer classes must declare associations explicitly, using `belongs_to` and `has_many` and etc., for `include` option to work. |
There was a problem hiding this comment.
Maybe something like:
Which serializer associations are rendered can be specified using the
includeoption. The option usage is consistent with theincludeoption in the JSON API spec, but is available in all adapters. The defaultincludefor the JSON API adapter is no associations. The default for the JSON and Attributes adapters is all associations.
There was a problem hiding this comment.
It might be good to also have an example that mixes fields with include unless there's another somewhere.
docs/general/adapters.md
Outdated
|
|
||
| ```ruby | ||
| render json: @posts, include: ['author', 'comments', 'comments.author'] | ||
| # or | ||
| render json: @posts, include: 'author,comments,comments.author' | ||
| ``` | ||
| **Note:** Serializer classes must declare associations explicitly, using `belongs_to` and `has_many` and etc., for `include` option to work. | ||
|
|
||
| For JSON API adapter associated resources will be gathered in the `"included"` member. | ||
|
|
||
| In addition, two types of wildcards may be used: |
There was a problem hiding this comment.
Maybe note the wildcards are AMS-specific.
There was a problem hiding this comment.
I am afraid, I don't fully understand, what does "AMS-specific" mean. Can you elaborate, please?
charlie-wasp
force-pushed
the
1243-add-docs-for-include
branch
from
4c051a1 to
ad13e2c
Compare
|
@bf4 I tried to embrace your thoughts :) |
docs/general/adapters.md
Outdated
| It will include the associated resources in the `"included"` member | ||
| when the resource names are included in the `include` option. | ||
| Including nested associated resources is also supported. | ||
| 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), but is available in all adapters. |
docs/general/adapters.md
Outdated
| @@ -182,6 +184,20 @@ It could be combined, like above, with other paths in any combination desired. | |||
| render json: @posts, include: 'author.comments.**' | |||
| ``` | |||
|
|
|||
| **Note:** Wildcards are AMS-specific, they are not part of the JSON API spec. | |||
|
|
||
| - 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. |
|
@charlie-wasp I think it looks great! Please make the two word changes and add yourself to the changelog under |
|
@bf4 done! |
|
@bf4 Hello, any updates on this? |
|
@charlie-wasp Sorry for the delay :( great job! |
* Add docs for `include` option in the adapter
* Add docs for `include` option in the adapter
Purpose
This PR addresses #1243, adding missing docs about include option for not JSON API adapters.
Related GitHub issues
#1243
This is my first documentation PR, and I will be glad to make it better! :)