From b0a2e9f5e21d1fbad148ec33a98adfe8597196c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Moura?= Date: Wed, 8 Jul 2015 11:47:24 -0300 Subject: [PATCH 1/4] starting initial docs structure --- docs/README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..5fc349b1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,26 @@ +# Docs - ActiveModel::Serializer 0.10.x + +This is the documentation of AMS, it's focused on **0.10.x version.** + +----- + +## General + +- [Getting Started](general/getting_started.md) +- [Adapters](general/adapters.md) + +## How to + +- [How to use add root key](howto/add_root_key.md) + +## Getting Help + +If you find a bug, please report an [Issue](https://github.com/rails-api/active_model_serializers/issues/new). + +If you have a question, please [post to Stack Overflow](http://stackoverflow.com/questions/tagged/active-model-serializers). + +Thanks! + +## Contributing + +See [CONTRIBUTING.md](https://github.com/rails-api/active_model_serializers/blob/master/CONTRIBUTING.md) From 420f7959c069ef4169ed65604b44fa8f2d7eb0a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Moura?= Date: Wed, 8 Jul 2015 15:05:40 -0300 Subject: [PATCH 2/4] creating initial general and how to docs --- docs/general/adapters.md | 52 +++++++++++++++++++++++ docs/general/getting_started.md | 75 +++++++++++++++++++++++++++++++++ docs/howto/add_root_key.md | 56 ++++++++++++++++++++++++ 3 files changed, 183 insertions(+) create mode 100644 docs/general/adapters.md create mode 100644 docs/general/getting_started.md create mode 100644 docs/howto/add_root_key.md diff --git a/docs/general/adapters.md b/docs/general/adapters.md new file mode 100644 index 00000000..a84fc4d3 --- /dev/null +++ b/docs/general/adapters.md @@ -0,0 +1,52 @@ +# Adapters + +AMS does this through two components: **serializers** and **adapters**. +Serializers describe _which_ attributes and relationships should be serialized. +Adapters describe _how_ attributes and relationships should be serialized. +You can use one of the built-in adapters (```FlattenJSON``` is the default one) or create one by your one but you won't need to implement an adapter unless you wish to use a new format or +media type with AMS. + +## Built in Adapters + +### FlattenJSON - Default + +It's the default adapter, it generates a json response without a root key. +Doesn't follow any specifc convention. + +### JSON + +It also generates a json response but always with a root key. The root key **can't be overridden**, and will be automatically defined accordingly with the objects being serialized. +Doesn't follow any specifc convention. + +### JSONAPI + +This adapter follows 1.0 of the format specified in +[jsonapi.org/format](http://jsonapi.org/format). It will include the associated +resources in the `"included"` member when the resource names are included in the +`include` option. + +```ruby + render @posts, include: ['authors', 'comments'] + # or + render @posts, include: 'authors,comments' +``` + +## Choose an Adapter + +If you want to use a different adapter, such as a JsonApi, you can change this in an initializer: + +```ruby +ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::JsonApi +``` + +or + +```ruby +ActiveModel::Serializer.config.adapter = :json_api +``` + +If you want to have a root key on your responses you should use the Json adapter, instead of the default FlattenJson: + +```ruby +ActiveModel::Serializer.config.adapter = :json +``` diff --git a/docs/general/getting_started.md b/docs/general/getting_started.md new file mode 100644 index 00000000..dda394e9 --- /dev/null +++ b/docs/general/getting_started.md @@ -0,0 +1,75 @@ +# Getting Started + +## Installation + +### ActiveModel::Serializer is already included on Rails >= 5 + +Add this line to your application's Gemfile: + +``` +gem 'active_model_serializers' +``` + +And then execute: + +``` +$ bundle +``` + +## Creating a Serializer + +The easiest way to create a new serializer is to generate a new resource, which +will generate a serializer at the same time: + +``` +$ rails g resource post title:string body:string +``` + +This will generate a serializer in `app/serializers/post_serializer.rb` for +your new model. You can also generate a serializer for an existing model with +the serializer generator: + +``` +$ rails g serializer post +``` + +The generated seralizer will contain basic `attributes` and +`has_many`/`has_one`/`belongs_to` declarations, based on the model. For example: + +```ruby +class PostSerializer < ActiveModel::Serializer + attributes :title, :body + + has_many :comments + has_one :author + + url :post +end +``` + +and + +```ruby +class CommentSerializer < ActiveModel::Serializer + attributes :name, :body + + belongs_to :post_id + + url [:post, :comment] +end +``` + +## Rails Integration + +AMS will automatically integrate with you Rails app, you won't need to update your controller, this is a example of how it will look like: + +```ruby +class PostsController < ApplicationController + + def show + @post = Post.find(params[:id]) + render json: @post + end + +end +``` diff --git a/docs/howto/add_root_key.md b/docs/howto/add_root_key.md new file mode 100644 index 00000000..37edbe82 --- /dev/null +++ b/docs/howto/add_root_key.md @@ -0,0 +1,56 @@ +# How to use add root key + +Add the root key to your API is quite simple with AMS. The **Adapter** is what determines the format of your JSON response. The default adapter is the ```FlattenJSON``` which doesn't have the root key, so your response is something similar to: + +```json +{ + id: 1, + title: "Awesome Post Tile", + content: "Post content" +} +``` + +In order to add the correspondent root key you need to use the ```JSON``` Adapter, you can change this in an initializer: + +```ruby +ActiveModel::Serializer.config.adapter = :json_api +``` + +or + +```ruby +ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::Json +``` + +This will add the root key to all your serialized endpoints. + +ex: + +```json +{ + post: { + id: 1, + title: "Awesome Post Tile", + content: "Post content" + } +} +``` + +or if it returns a collection: + +```json +{ + posts: [ + { + id: 1, + title: "Awesome Post Tile", + content: "Post content" + }, + { + id: 2, + title: "Another Post Tile", + content: "Another post content" + } + ] +} +``` From 456f9158ca596c6d9d85271b29c97d96ec904554 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Moura?= Date: Sun, 12 Jul 2015 00:13:29 -0300 Subject: [PATCH 3/4] removing useless exmaple lines --- docs/general/getting_started.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/general/getting_started.md b/docs/general/getting_started.md index dda394e9..72e84ae7 100644 --- a/docs/general/getting_started.md +++ b/docs/general/getting_started.md @@ -43,7 +43,6 @@ class PostSerializer < ActiveModel::Serializer has_many :comments has_one :author - url :post end ``` @@ -55,7 +54,6 @@ class CommentSerializer < ActiveModel::Serializer belongs_to :post_id - url [:post, :comment] end ``` From 63436c73e8e2eb0cf05a4e0ec90ad17a7451f978 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20M=2E=20D=2E=20Moura?= Date: Thu, 16 Jul 2015 23:29:03 -0400 Subject: [PATCH 4/4] minor updates and TYPOs --- docs/README.md | 4 ++-- docs/general/adapters.md | 13 ++++++------- docs/howto/add_root_key.md | 15 +++++---------- 3 files changed, 13 insertions(+), 19 deletions(-) diff --git a/docs/README.md b/docs/README.md index 5fc349b1..ddecb3e4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Docs - ActiveModel::Serializer 0.10.x -This is the documentation of AMS, it's focused on **0.10.x version.** +This is the documentation of AMS, it's focused on the **0.10.x version.** ----- @@ -11,7 +11,7 @@ This is the documentation of AMS, it's focused on **0.10.x version.** ## How to -- [How to use add root key](howto/add_root_key.md) +- [How to add root key](howto/add_root_key.md) ## Getting Help diff --git a/docs/general/adapters.md b/docs/general/adapters.md index a84fc4d3..60dc9842 100644 --- a/docs/general/adapters.md +++ b/docs/general/adapters.md @@ -3,8 +3,7 @@ AMS does this through two components: **serializers** and **adapters**. Serializers describe _which_ attributes and relationships should be serialized. Adapters describe _how_ attributes and relationships should be serialized. -You can use one of the built-in adapters (```FlattenJSON``` is the default one) or create one by your one but you won't need to implement an adapter unless you wish to use a new format or -media type with AMS. +You can use one of the built-in adapters (```FlattenJSON``` is the default one) or create one by yourself, but you won't need to implement an adapter unless you wish to use a new format or media type with AMS. ## Built in Adapters @@ -15,12 +14,12 @@ Doesn't follow any specifc convention. ### JSON -It also generates a json response but always with a root key. The root key **can't be overridden**, and will be automatically defined accordingly with the objects being serialized. +It also generates a json response but always with a root key. The root key **can't be overridden**, and will be automatically defined accordingly to the objects being serialized. Doesn't follow any specifc convention. ### JSONAPI -This adapter follows 1.0 of the format specified in +This adapter follows **version 1.0** of the format specified in [jsonapi.org/format](http://jsonapi.org/format). It will include the associated resources in the `"included"` member when the resource names are included in the `include` option. @@ -31,9 +30,9 @@ resources in the `"included"` member when the resource names are included in the render @posts, include: 'authors,comments' ``` -## Choose an Adapter +## Choosing an adapter -If you want to use a different adapter, such as a JsonApi, you can change this in an initializer: +If you want to use a different adapter, such as JsonApi, you can change this in an initializer: ```ruby ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::JsonApi @@ -45,7 +44,7 @@ or ActiveModel::Serializer.config.adapter = :json_api ``` -If you want to have a root key on your responses you should use the Json adapter, instead of the default FlattenJson: +If you want to have a root key in your responses you should use the Json adapter, instead of the default FlattenJson: ```ruby ActiveModel::Serializer.config.adapter = :json diff --git a/docs/howto/add_root_key.md b/docs/howto/add_root_key.md index 37edbe82..6c1d7aa7 100644 --- a/docs/howto/add_root_key.md +++ b/docs/howto/add_root_key.md @@ -1,4 +1,4 @@ -# How to use add root key +# How to add root key Add the root key to your API is quite simple with AMS. The **Adapter** is what determines the format of your JSON response. The default adapter is the ```FlattenJSON``` which doesn't have the root key, so your response is something similar to: @@ -10,19 +10,14 @@ Add the root key to your API is quite simple with AMS. The **Adapter** is what d } ``` -In order to add the correspondent root key you need to use the ```JSON``` Adapter, you can change this in an initializer: +In order to add the root key you need to use the ```JSON``` Adapter, you can change this in an initializer: ```ruby -ActiveModel::Serializer.config.adapter = :json_api +ActiveModel::Serializer.config.adapter = :json ``` -or - -```ruby -ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::Json -``` - -This will add the root key to all your serialized endpoints. +You can also specify a class as adapter, as long as it complies with the AMS adapters interface. +It will add the root key to all your serialized endpoints. ex: