active_model_serializers 0.10.0 → 0.10.13

data/docs/howto/test.md

@@ -1,152 +0,0 @@
-# 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"
-    }
-  }
-}
-```

data/docs/integrations/ember-and-json-api.md

@@ -1,112 +0,0 @@
-[Back to Guides](../README.md)
-
-# Integrating with Ember and JSON API
-
- - [Preparation](./ember-and-json-api.md#preparation)
- - [Server-Side Changes](./ember-and-json-api.md#server-side-changes)
- - [Adapter Changes](./ember-and-json-api.md#adapter-changes)
-   - [Serializer Changes](./ember-and-json-api.md#serializer-changes)
- - [Including Nested Resources](./ember-and-json-api.md#including-nested-resources)
-
-## Preparation
-
-Note: This guide assumes that `ember-cli` is used for your ember app.
-
-The JSON API specification calls for hyphens for multi-word separators. ActiveModelSerializers uses underscores.
-To solve this, in Ember, both the adapter and the serializer will need some modifications:
-
-### Server-Side Changes
-
-there are multiple mimetypes for json that should all be parsed similarly, so
-in `config/initializers/mime_types.rb`:
-```ruby
-api_mime_types = %W(
-  application/vnd.api+json
-  text/x-json
-  application/json
-)
-
-Mime::Type.unregister :json
-Mime::Type.register 'application/json', :json, api_mime_types
-```
-
-### Adapter Changes
-
-```javascript
-// app/adapters/application.js
-import DS from 'ember-data';
-import ENV from "../config/environment";
-
-export default  DS.JSONAPIAdapter.extend({
-  namespace: 'api',
-  // if your rails app is on a different port from your ember app
-  // this can be helpful for development.
-  // in production, the host for both rails and ember should be the same.
-  host: ENV.host,
-
-  // allows the multiword paths in urls to be underscored
-  pathForType: function(type) {
-    let underscored = Ember.String.underscore(type);
-    return Ember.String.pluralize(underscored);
-  },
-
-  // allows queries to be sent along with a findRecord
-  // hopefully Ember / EmberData will soon have this built in
-  // ember-data issue tracked here:
-  // https://github.com/emberjs/data/issues/3596
-  urlForFindRecord(id, modelName, snapshot) {
-    let url = this._super(...arguments);
-    let query = Ember.get(snapshot, 'adapterOptions.query');
-    if(query) {
-      url += '?' + Ember.$.param(query);
-    }
-    return url;
-  }
-});
-```
-
-### Serializer Changes
-
-```javascript
-// app/serializers/application.js
-import Ember from 'ember';
-import DS from 'ember-data';
-var underscore = Ember.String.underscore;
-
-export default DS.JSONAPISerializer.extend({
-  keyForAttribute: function(attr) {
-    return underscore(attr);
-  },
-
-  keyForRelationship: function(rawKey) {
-    return underscore(rawKey);
-  }
-});
-
-```
-
-## Including Nested Resources
-
-Previously, `store.find` and `store.findRecord` did not allow specification of any query params.
-The ActiveModelSerializers default for the `include` parameter is to be `nil` meaning that if any associations are defined in your serializer, only the `id` and `type` will be in the `relationships` structure of the JSON API response.
-For more on `include` usage, see: [The JSON API include examples](./../general/adapters.md#JSON-API)
-
-With the above modifications, you can execute code as below in order to include nested resources while doing a find query.
-
-```javascript
-store.findRecord('post', postId, { adapterOptions: { query: { include: 'comments' } } });
-```
-will generate the path `/posts/{postId}?include='comments'`
-
-So then in your controller, you'll want to be sure to have something like:
-```ruby
-render json: @post, include: params[:include]
-```
-
-If you want to use `include` on a collection, you'd write something like this:
-
-```javascript
-store.query('post', { include: 'comments' });
-```
-
-which will generate the path `/posts?include='comments'`

data/docs/integrations/grape.md

@@ -1,19 +0,0 @@
-# Integration with Grape
-
-[Grape](https://github.com/ruby-grape/grape) is an opinionated micro-framework for creating REST-like APIs in ruby.
-
-ActiveModelSerializers currently supports Grape >= 0.13, < 1.0
-
-To add [Grape](https://github.com/ruby-grape/grape) support, enable the formatter and helper functions by including `Grape::ActiveModelSerializers` in your base endpoint. For example:
-
-```ruby
-module Example
-  class Dummy < Grape::API
-    require 'grape/active_model_serializers'
-    include Grape::ActiveModelSerializers
-    mount Example::V1::Base
-  end
-end
-```
-
-Aside from this, [configuration](../general/configuration_options.md) of ActiveModelSerializers is exactly the same.

data/docs/jsonapi/errors.md

@@ -1,56 +0,0 @@
-[Back to Guides](../README.md)
-
-# [JSON API Errors](http://jsonapi.org/format/#errors)
-
-Rendering error documents requires specifying the error serializer(s):
-
-- Serializer:
-  - For a single resource: `serializer: ActiveModel::Serializer::ErrorSerializer`.
-  - For a collection: `serializer: ActiveModel::Serializer::ErrorsSerializer`, `each_serializer: ActiveModel::Serializer::ErrorSerializer`.
-
-The resource **MUST** have a non-empty associated `#errors` object.
-The `errors` object must have a `#messages` method that returns a hash of error name to array of
-descriptions.
-
-## Use in controllers
-
-```ruby
-resource = Profile.new(name: 'Name 1',
-                       description: 'Description 1',
-                       comments: 'Comments 1')
-resource.errors.add(:name, 'cannot be nil')
-resource.errors.add(:name, 'must be longer')
-resource.errors.add(:id, 'must be a uuid')
-
-render json: resource, status: 422, adapter: :json_api, serializer: ActiveModel::Serializer::ErrorSerializer
-# #=>
-#  { :errors =>
-#    [
-#      { :source => { :pointer => '/data/attributes/name' }, :detail => 'cannot be nil' },
-#      { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be longer' },
-#      { :source => { :pointer => '/data/attributes/id' }, :detail => 'must be a uuid' }
-#    ]
-#  }.to_json
-```
-
-## Direct error document generation
-
-```ruby
-options = nil
-resource = ModelWithErrors.new
-resource.errors.add(:name, 'must be awesome')
-
-serializable_resource = ActiveModelSerializers::SerializableResource.new(
-  resource, {
-    serializer: ActiveModel::Serializer::ErrorSerializer,
-    adapter: :json_api
-  })
-serializable_resource.as_json(options)
-# #=>
-# {
-#   :errors =>
-#     [
-#       { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be awesome' }
-#     ]
-# }
-```

data/docs/jsonapi/schema/schema.json

@@ -1,366 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-04/schema#",
-  "title": "JSON API Schema",
-  "description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
-  "oneOf": [
-    {
-      "$ref": "#/definitions/success"
-    },
-    {
-      "$ref": "#/definitions/failure"
-    },
-    {
-      "$ref": "#/definitions/info"
-    }
-  ],
-  
-  "definitions": {
-    "success": {
-      "type": "object",
-      "required": [
-        "data"
-      ],
-      "properties": {
-        "data": {
-          "$ref": "#/definitions/data"
-        },
-        "included": {
-          "description": "To reduce the number of HTTP requests, servers **MAY** allow responses that include related resources along with the requested primary resources. Such responses are called \"compound documents\".",
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/resource"
-          },
-          "uniqueItems": true
-        },
-        "meta": {
-          "$ref": "#/definitions/meta"
-        },
-        "links": {
-          "description": "Link members related to the primary data.",
-          "allOf": [
-            {
-              "$ref": "#/definitions/links"
-            },
-            {
-              "$ref": "#/definitions/pagination"
-            }
-          ]
-        },
-        "jsonapi": {
-          "$ref": "#/definitions/jsonapi"
-        }
-      },
-      "additionalProperties": false
-    },
-    "failure": {
-      "type": "object",
-      "required": [
-        "errors"
-      ],
-      "properties": {
-        "errors": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/error"
-          },
-          "uniqueItems": true
-        },
-        "meta": {
-          "$ref": "#/definitions/meta"
-        },
-        "jsonapi": {
-          "$ref": "#/definitions/jsonapi"
-        }
-      },
-      "additionalProperties": false
-    },
-    "info": {
-      "type": "object",
-      "required": [
-        "meta"
-      ],
-      "properties": {
-        "meta": {
-          "$ref": "#/definitions/meta"
-        },
-        "links": {
-          "$ref": "#/definitions/links"
-        },
-        "jsonapi": {
-          "$ref": "#/definitions/jsonapi"
-        }
-      },
-      "additionalProperties": false
-    },
-    
-    "meta": {
-      "description": "Non-standard meta-information that can not be represented as an attribute or relationship.",
-      "type": "object",
-      "additionalProperties": true
-    },
-    "data": {
-      "description": "The document's \"primary data\" is a representation of the resource or collection of resources targeted by a request.",
-      "oneOf": [
-        {
-          "$ref": "#/definitions/resource"
-        },
-        {
-          "description": "An array of resource objects, an array of resource identifier objects, or an empty array ([]), for requests that target resource collections.",
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/resource"
-          },
-          "uniqueItems": true
-        }
-      ]
-    },
-    "resource": {
-      "description": "\"Resource objects\" appear in a JSON API document to represent resources.",
-      "type": "object",
-      "required": [
-        "type",
-        "id"
-      ],
-      "properties": {
-        "type": {
-          "type": "string"
-        },
-        "id": {
-          "type": "string"
-        },
-        "attributes": {
-          "$ref": "#/definitions/attributes"
-        },
-        "relationships": {
-          "$ref": "#/definitions/relationships"
-        },
-        "links": {
-          "$ref": "#/definitions/links"
-        },
-        "meta": {
-          "$ref": "#/definitions/meta"
-        }
-      },
-      "additionalProperties": false
-    },
-    
-    "links": {
-      "description": "A resource object **MAY** contain references to other resource objects (\"relationships\"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.",
-      "type": "object",
-      "properties": {
-        "self": {
-          "description": "A `self` member, whose value is a URL for the relationship itself (a \"relationship URL\"). This URL allows the client to directly manipulate the relationship. For example, it would allow a client to remove an `author` from an `article` without deleting the people resource itself.",
-          "type": "string",
-          "format": "uri"
-        },
-        "related": {
-          "$ref": "#/definitions/link"
-        }
-      },
-      "additionalProperties": true
-    },
-    "link": {
-      "description": "A link **MUST** be represented as either: a string containing the link's URL or a link object.",
-      "oneOf": [
-        {
-          "description": "A string containing the link's URL.",
-          "type": "string",
-          "format": "uri"
-        },
-        {
-          "type": "object",
-          "required": [
-            "href"
-          ],
-          "properties": {
-            "href": {
-              "description": "A string containing the link's URL.",
-              "type": "string",
-              "format": "uri"
-            },
-            "meta": {
-              "$ref": "#/definitions/meta"
-            }
-          }
-        }
-      ]
-    },
-
-    "attributes": {
-      "description": "Members of the attributes object (\"attributes\") represent information about the resource object in which it's defined.",
-      "type": "object",
-      "patternProperties": {
-        "^(?!relationships$|links$)\\w[-\\w_]*$": {
-          "description": "Attributes may contain any valid JSON value."
-        }
-      },
-      "additionalProperties": false
-    },
-
-    "relationships": {
-      "description": "Members of the relationships object (\"relationships\") represent references from the resource object in which it's defined to other resource objects.",
-      "type": "object",
-      "patternProperties": {
-        "^\\w[-\\w_]*$": {
-          "properties": {
-            "links": {
-              "$ref": "#/definitions/links"
-            },
-            "data": {
-              "description": "Member, whose value represents \"resource linkage\".",
-              "oneOf": [
-                {
-                  "$ref": "#/definitions/relationshipToOne"
-                },
-                {
-                  "$ref": "#/definitions/relationshipToMany"
-                }
-              ]
-            },
-            "meta": {
-              "$ref": "#/definitions/meta"
-            }
-          },
-          "additionalProperties": false
-        }
-      },
-      "additionalProperties": false
-    },
-    "relationshipToOne": {
-      "description": "References to other resource objects in a to-one (\"relationship\"). Relationships can be specified by including a member in a resource's links object.",
-      "anyOf": [
-        {
-          "$ref": "#/definitions/empty"
-        },
-        {
-          "$ref": "#/definitions/linkage"
-        }
-      ]
-    },
-    "relationshipToMany": {
-      "description": "An array of objects each containing \"type\" and \"id\" members for to-many relationships.",
-      "type": "array",
-      "items": {
-        "$ref": "#/definitions/linkage"
-      },
-      "uniqueItems": true
-    },
-    "empty": {
-      "description": "Describes an empty to-one relationship.",
-      "type": "null"
-    },
-    "linkage": {
-      "description": "The \"type\" and \"id\" to non-empty members.",
-      "type": "object",
-      "required": [
-        "type",
-        "id"
-      ],
-      "properties": {
-        "type": {
-          "type": "string"
-        },
-        "id": {
-          "type": "string"
-        },
-        "meta": {
-          "$ref": "#/definitions/meta"
-        }
-      },
-      "additionalProperties": false
-    },
-    "pagination": {
-      "type": "object",
-      "properties": {
-        "first": {
-          "description": "The first page of data",
-          "oneOf": [
-            { "type": "string", "format": "uri" },
-            { "type": "null" }
-          ]
-        },
-        "last": {
-          "description": "The last page of data",
-          "oneOf": [
-            { "type": "string", "format": "uri" },
-            { "type": "null" }
-          ]
-        },
-        "prev": {
-          "description": "The previous page of data",
-          "oneOf": [
-            { "type": "string", "format": "uri" },
-            { "type": "null" }
-          ]
-        },
-        "next": {
-          "description": "The next page of data",
-          "oneOf": [
-            { "type": "string", "format": "uri" },
-            { "type": "null" }
-          ]
-        }
-      }
-    },
-    
-    "jsonapi": {
-      "description": "An object describing the server's implementation",
-      "type": "object",
-      "properties": {
-        "version": {
-          "type": "string"
-        },
-        "meta": {
-          "$ref": "#/definitions/meta"
-        }
-      },
-      "additionalProperties": false
-    },
-    
-    "error": {
-      "type": "object",
-      "properties": {
-        "id": {
-          "description": "A unique identifier for this particular occurrence of the problem.",
-          "type": "string"
-        },
-        "links": {
-          "$ref": "#/definitions/links"
-        },
-        "status": {
-          "description": "The HTTP status code applicable to this problem, expressed as a string value.",
-          "type": "string"
-        },
-        "code": {
-          "description": "An application-specific error code, expressed as a string value.",
-          "type": "string"
-        },
-        "title": {
-          "description": "A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization.",
-          "type": "string"
-        },
-        "detail": {
-          "description": "A human-readable explanation specific to this occurrence of the problem.",
-          "type": "string"
-        },
-        "source": {
-          "type": "object",
-          "properties": {
-            "pointer": {
-              "description": "A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. \"/data\" for a primary data object, or \"/data/attributes/title\" for a specific attribute].",
-              "type": "string"
-            },
-            "parameter": {
-              "description": "A string indicating which query parameter caused the error.",
-              "type": "string"
-            }
-          }
-        },
-        "meta": {
-          "$ref": "#/definitions/meta"
-        }
-      },
-      "additionalProperties": false
-    }
-  }
-}