Merge pull request #994 from joaomdmoura/master

Starting Docs structure

Author: joaomdmoura

docs/README.md

@@ -0,0 +1,26 @@
+# Docs - ActiveModel::Serializer 0.10.x
+
+This is the documentation of AMS, it's focused on the **0.10.x version.**
+
+-----
+
+## General
+
+- [Getting Started](general/getting_started.md)
+- [Adapters](general/adapters.md)
+
+## How to
+
+- [How to 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)

docs/general/adapters.md

@@ -0,0 +1,51 @@
+# 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 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
+
+### 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 to the objects being serialized.
+Doesn't follow any specifc convention.
+
+### JSONAPI
+
+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.
+
+```ruby
+  render @posts, include: ['authors', 'comments']
+  # or
+  render @posts, include: 'authors,comments'
+```
+
+## Choosing an adapter
+
+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
+```
+
+or
+
+```ruby
+ActiveModel::Serializer.config.adapter = :json_api
+```
+
+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
+```

docs/general/getting_started.md

@@ -0,0 +1,73 @@
+# 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
+
+end
+```
+
+and
+
+```ruby
+class CommentSerializer < ActiveModel::Serializer
+  attributes :name, :body
+
+  belongs_to :post_id
+
+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
+```

docs/howto/add_root_key.md

@@ -0,0 +1,51 @@
+# 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:
+
+```json
+{
+  id: 1,
+  title: "Awesome Post Tile",
+  content: "Post content"
+}
+```
+
+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
+```
+
+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:
+
+```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"
+    }
+  ]
+}
+```