active_model_serializers 0.10.0.rc3 → 0.10.0.rc4

data/docs/general/serializers.md

@@ -0,0 +1,207 @@
+[Back to Guides](../README.md)
+
+# Serializers
+
+Given a serializer class:
+
+```ruby
+class SomeSerializer < ActiveModel::Serializer
+end
+```
+
+The following methods may be defined in it:
+
+### Attributes
+
+#### ::attributes
+
+Serialization of the resource `title` and `body`
+
+| In Serializer               | #attributes |
+|---------------------------- |-------------|
+| `attributes :title, :body`  | `{ title: 'Some Title', body: 'Some Body' }`
+| `attributes :title, :body`<br>`def body "Special #{object.body}" end` | `{ title: 'Some Title', body: 'Special Some Body' }`
+
+
+#### ::attribute
+
+Serialization of the resource `title`
+
+| In Serializer               | #attributes |
+|---------------------------- |-------------|
+| `attribute :title`          | `{ title: 'Some Title' } `
+| `attribute :title, key: :name` | `{ name: 'Some Title' } `
+| `attribute :title { 'A Different Title'}` | `{ title: 'A Different Title' } `
+| `attribute :title`<br>`def title 'A Different Title' end` | `{ title: 'A Different Title' }`
+
+[PR please for conditional attributes:)](https://github.com/rails-api/active_model_serializers/pull/1403)
+
+### Associations
+
+#### ::has_one
+
+e.g.
+
+```ruby
+has_one :bio
+has_one :blog, key: :site
+has_one :maker, virtual_value: { id: 1 }
+```
+
+#### ::has_many
+
+e.g.
+
+```ruby
+has_many :comments
+has_many :comments, key: :reviews
+has_many :comments, serializer: CommentPreviewSerializer
+has_many :reviews, virtual_value: [{ id: 1 }, { id: 2 }]
+has_many :comments, key: :last_comments do
+  last(1)
+end
+```
+
+#### ::belongs_to
+
+e.g.
+
+```ruby
+belongs_to :author, serializer: AuthorPreviewSerializer
+belongs_to :author, key: :writer
+belongs_to :post
+belongs_to :blog
+def blog
+  Blog.new(id: 999, name: 'Custom blog')
+end
+```
+
+### Caching
+
+#### ::cache
+
+e.g.
+
+```ruby
+cache key: 'post', expires_in: 0.1, skip_digest: true
+cache expires_in: 1.day, skip_digest: true
+cache key: 'writer', skip_digest: true
+cache only: [:name], skip_digest: true
+cache except: [:content], skip_digest: true
+cache key: 'blog'
+cache only: [:id]
+```
+
+#### #cache_key
+
+e.g.
+
+```ruby
+# Uses a custom non-time-based cache key
+def cache_key
+  "#{self.class.name.downcase}/#{self.id}"
+end
+```
+
+### Other
+
+#### ::type
+
+e.g.
+
+```ruby
+class UserProfileSerializer < ActiveModel::Serializer
+  type 'profile'
+end
+```
+
+#### ::link
+
+e.g.
+
+```ruby
+link :other, 'https://example.com/resource'
+link :self do
+ href "https://example.com/link_author/#{object.id}"
+end
+```
+
+#### #object
+
+The object being serialized.
+
+#### #root
+
+PR please :)
+
+#### #scope
+
+PR please :)
+
+#### #read_attribute_for_serialization(key)
+
+The serialized value for a given key. e.g. `read_attribute_for_serialization(:title) #=> 'Hello World'`
+
+#### #links
+
+PR please :)
+
+#### #json_key
+
+PR please :)
+
+## Examples
+
+Given two models, a `Post(title: string, body: text)` and a
+`Comment(name: string, body: text, post_id: integer)`, you will have two
+serializers:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  cache key: 'posts', expires_in: 3.hours
+  attributes :title, :body
+
+  has_many :comments
+end
+```
+
+and
+
+```ruby
+class CommentSerializer < ActiveModel::Serializer
+  attributes :name, :body
+
+  belongs_to :post
+end
+```
+
+Generally speaking, you, as a user of ActiveModelSerializers, will write (or generate) these
+serializer classes.
+
+## More Info
+
+For more information, see [the Serializer class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer.rb)
+
+## Overriding association methods
+
+To override an association, call `has_many`, `has_one` or `belongs_to` with a block:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  has_many :comments do
+    object.comments.active
+  end
+end
+```
+
+## Overriding attribute methods
+
+To override an attribute, call `attribute` with a block:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attribute :body do
+    object.body.downcase
+  end
+end
+```

data/docs/howto/add_pagination_links.md

@@ -1,12 +1,21 @@
+[Back to Guides](../README.md)
+
 # How to add pagination links
 
-### JSON-API adapter
+### JSON API adapter
+
+Pagination links will be included in your response automatically as long as
+the resource is paginated and if you are using the ```JsonApi``` adapter.
 
-Pagination links will be included in your response automatically as long as the resource is paginated and if you are using a ```JSON-API``` adapter.
+If you want pagination links in your response, use [Kaminari](https://github.com/amatsuda/kaminari)
+or [WillPaginate](https://github.com/mislav/will_paginate).
 
-If you want pagination links in your response, use [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
+Although the others adapters does not have this feature, it is possible to
+implement pagination links to `JSON` adapter. For more information about it,
+please see in our docs 
 
 ###### Kaminari examples
+
 ```ruby
 #array
 @posts = Kaminari.paginate_array([1, 2, 3]).page(3).per(1)
@@ -30,7 +39,7 @@ render json: @posts
 ```
 
 ```ruby
-ActiveModel::Serializer.config.adapter = :json_api
+ActiveModelSerializers.config.adapter = :json_api
 ```
 
 ex:
@@ -58,7 +67,7 @@ ex:
 }
 ```
 
-AMS pagination relies on a paginated collection with the methods `current_page`, `total_pages`, and `size`, such as are supported by both [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
+ActiveModelSerializers pagination relies on a paginated collection with the methods `current_page`, `total_pages`, and `size`, such as are supported by both [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
 
 
 ### JSON adapter
@@ -72,7 +81,7 @@ render json: @posts, serializer: PaginatedSerializer, each_serializer: PostPrevi
 
 And then, you could do something like the following class.
 ```ruby
-class PaginatedSerializer < ActiveModel::Serializer::ArraySerializer
+class PaginatedSerializer < ActiveModel::Serializer::CollectionSerializer
   def initialize(object, options={})
     meta_key = options[:meta_key] || :meta
     options[meta_key] ||= {}
@@ -107,6 +116,6 @@ ex.
 }
 ```
 
-### FlattenJSON adapter
+### Attributes adapter
 
 This adapter does not allow us to use `meta` key, due to that it is not possible to add pagination links.

data/docs/howto/add_root_key.md

@@ -1,6 +1,6 @@
 # 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:
+Add the root key to your API is quite simple with ActiveModelSerializers. The **Adapter** is what determines the format of your JSON response. The default adapter is the ```Attributes``` which doesn't have the root key, so your response is something similar to:
 
 ```json
 {
@@ -13,10 +13,10 @@ Add the root key to your API is quite simple with AMS. The **Adapter** is what d
 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
+ActiveModelSerializers.config.adapter = :json
 ```
 
-You can also specify a class as adapter, as long as it complies with the AMS adapters interface.
+You can also specify a class as adapter, as long as it complies with the ActiveModelSerializers adapters interface.
 It will add the root key to all your serialized endpoints.
 
 ex:

data/docs/howto/outside_controller_use.md

@@ -1,8 +1,10 @@
-## Using AMS Outside Of A Controller
+[Back to Guides](../README.md)
 
-### Serializing a resource 
+## Using ActiveModelSerializers Outside Of A Controller
 
-In AMS versions 0.10 or later, serializing resources outside of the controller context is fairly simple:
+### Serializing a resource
+
+In ActiveModelSerializers versions 0.10 or later, serializing resources outside of the controller context is fairly simple:
 
 ```ruby
 # Create our resource
@@ -16,14 +18,14 @@ serializable_resource = ActiveModel::SerializableResource.new(post, options)
 
 # Convert your resource into json
 model_json = serializable_resource.as_json
-``` 
+```
 
-### Retrieving a Resource's Active Model Serializer
+### Looking up the Serializer for a Resource
 
 If you want to retrieve a serializer for a specific resource, you can do the following:
 
 ```ruby
-# Create our resource 
+# Create our resource
 post = Post.create(title: "Another Example", body: "So much fun.")
 
 # Optional options parameters
@@ -33,10 +35,24 @@ options = {}
 serializer = ActiveModel::Serializer.serializer_for(post, options)
 ```
 
-You could also retrieve the serializer via: 
+You could also retrieve the serializer via:
 
 ```ruby
-ActiveModel::SerializableResource.new(post, options).serializer 
+ActiveModel::SerializableResource.new(post, options).serializer
 ```
 
-Both approaches will return an instance, if any, of the resource's serializer.
+Both approaches will return an instance, if any, of the resource's serializer.
+
+## Serializing before controller render
+
+At times, you might want to use a serializer without rendering it to the view. For those cases, you can create an instance of `ActiveModel::SerializableResource` with
+the resource you want to be serialized and call `.as_json`.
+
+```ruby
+def create
+  message = current_user.messages.create!(message_params)
+  message_json = ActiveModel::SerializableResource.new(message).as_json
+  MessageCreationWorker.perform(message_json)
+  head 204
+end
+```

data/docs/howto/test.md

@@ -0,0 +1,152 @@
+# How to test
+
+## Controller Serializer Usage
+
+ActiveModelSerializers provides a `assert_serializer` method to be used on your controller tests to
+assert that a specific serializer was used.
+
+```ruby
+class PostsControllerTest < ActionController::TestCase
+  test "should render post serializer" do
+    get :index
+    assert_serializer "PostSerializer"
+  end
+end
+```
+
+See [ActiveModelSerializers::Test::Serializer](../../lib/active_model_serializers/test/serializer.rb)
+for more examples and documentation.
+
+## Serialization against a schema
+
+### Dependencies
+
+To use the `assert_response_schema` you need to have the
+[`json_schema`](https://github.com/brandur/json_schema) on your Gemfile. Please
+add it to your Gemfile and run `$ bundle install`.
+
+### Minitest test helpers
+
+ActiveModelSerializers provides a `assert_response_schema` method to be used on your controller tests to
+assert the response against a [JSON Schema](http://json-schema.org/). Let's take
+a look in an example.
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+
+    render json: @post
+  end
+end
+```
+
+To test the `posts#show` response of this controller we need to create a file
+named `test/support/schemas/posts/show.json`. The helper uses a naming convention
+to locate the file.
+
+This file is a JSON Schema representation of our response.
+
+```json
+{
+  "properties": {
+    "title" : { "type" : "string" },
+    "content" : { "type" : "string" }
+  }
+}
+```
+
+With all in place we can go to our test and use the helper.
+
+```ruby
+class PostsControllerTest < ActionController::TestCase
+  test "should render right response" do
+    get :index
+    assert_response_schema
+  end
+end
+```
+
+#### Load a custom schema
+
+If we need to use another schema, for example when we have a namespaced API that
+shows the same response, we can pass the path of the schema.
+
+```ruby
+module V1
+  class PostsController < ApplicationController
+    def show
+      @post = Post.find(params[:id])
+
+      render json: @post
+    end
+  end
+end
+```
+
+```ruby
+class V1::PostsControllerTest < ActionController::TestCase
+  test "should render right response" do
+    get :index
+    assert_response_schema('posts/show.json')
+  end
+end
+```
+
+#### Change the schema path
+
+By default all schemas are created at `test/support/schemas`. If we are using
+RSpec for example we can change this to `spec/support/schemas` defining the
+default schema path in an initializer.
+
+```ruby
+ActiveModelSerializers.config.schema_path = 'spec/support/schemas'
+```
+
+#### Using with the Heroku’s JSON Schema-based tools
+
+To use the test helper with the [prmd](https://github.com/interagent/prmd) and
+[committee](https://github.com/interagent/committee).
+
+We need to change the schema path to the recommended by prmd:
+
+```ruby
+ActiveModelSerializers.config.schema_path = 'docs/schema/schemata'
+```
+
+We also need to structure our schemata according to Heroku's conventions
+(e.g. including
+[required metadata](https://github.com/interagent/prmd/blob/master/docs/schemata.md#meta-data)
+and [links](https://github.com/interagent/prmd/blob/master/docs/schemata.md#links).
+
+#### JSON Pointers
+
+If we plan to use [JSON
+Pointers](http://spacetelescope.github.io/understanding-json-schema/UnderstandingJSONSchema.pdf) we need to define the `id` attribute on the schema. Example:
+
+```js
+// attributes.json
+
+{
+  "id": "file://attributes.json#",
+  "properties": {
+    "name" : { "type" : "string" },
+    "description" : { "type" : "string" }
+  }
+}
+```
+
+```js
+// show.json
+
+{
+  "properties": {
+    "name": {
+      "$ref": "file://attributes.json#/properties/name"
+    },
+    "description": {
+      "$ref": "file://attributes.json#/properties/description"
+    }
+  }
+}
+```