ditkrg/active_model_serializers
4
0
Fork 0
mirror of https://github.com/ditkrg/active_model_serializers.git synced 2026-01-25 07:16:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation with Yard links

Browse Source
This commit is contained in:
Benjamin Fleischer 2016-02-26 00:26:02 -06:00
parent 3d986377b6
commit e6ae34b84c
6 changed files with 50 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGELOG.md
View File

@ -3,6 +3,9 @@
Breaking changes: Breaking changes:
Features: Features:
- [#1004](https://github.com/rails-api/active_model_serializers/pull/1004) JSON API errors object implementation.
- Only implements `detail` and `source` as derived from `ActiveModel::Error`
- Provides checklist of remaining questions and remaining parts of the spec.
- [#1515](https://github.com/rails-api/active_model_serializers/pull/1515) Adds support for symbols to the - [#1515](https://github.com/rails-api/active_model_serializers/pull/1515) Adds support for symbols to the
`ActiveModel::Serializer.type` method. (@groyoh) `ActiveModel::Serializer.type` method. (@groyoh)
- [#1504](https://github.com/rails-api/active_model_serializers/pull/1504) Adds the changes missing from #1454 - [#1504](https://github.com/rails-api/active_model_serializers/pull/1504) Adds the changes missing from #1454

2
docs/jsonapi/errors.md
View File

@ -1,6 +1,6 @@
[Back to Guides](../README.md) [Back to Guides](../README.md)
# JSON API Errors # [JSON API Errors](http://jsonapi.org/format/#errors)
Rendering error documents requires specifying the error serializer(s): Rendering error documents requires specifying the error serializer(s):

45
docs/jsonapi/schema.md
View File

@ -58,33 +58,33 @@ Example supported requests
|-----------------------|----------------------------------------------------------------------------------------------------|----------|---------------------------------------| |-----------------------|----------------------------------------------------------------------------------------------------|----------|---------------------------------------|
| schema | oneOf (success, failure, info) | | | schema | oneOf (success, failure, info) | |
| success | data, included, meta, links, jsonapi | | AM::SerializableResource | success | data, included, meta, links, jsonapi | | AM::SerializableResource
| success.meta | meta | | AM::S::Adapter::Base#meta | success.meta | meta | | AMS::Adapter::Base#meta
| success.included | UniqueArray(resource) | | AM::S::Adapter::JsonApi#serializable_hash_for_collection | success.included | UniqueArray(resource) | | AMS::Adapter::JsonApi#serializable_hash_for_collection
| success.data | data | | | success.data | data | |
| success.links | allOf (links, pagination) | | AM::S::Adapter::JsonApi#links_for | success.links | allOf (links, pagination) | | AMS::Adapter::JsonApi#links_for
| success.jsonapi | jsonapi | | | success.jsonapi | jsonapi | |
| failure | errors, meta, jsonapi | errors | | failure | errors, meta, jsonapi | errors | AMS::Adapter::JsonApi#failure_document, #1004
| failure.errors | UniqueArray(error) | | #1004 | failure.errors | UniqueArray(error) | | AM::S::ErrorSerializer, #1004
| meta | Object | | | meta | Object | |
| data | oneOf (resource, UniqueArray(resource)) | | AM::S::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource | data | oneOf (resource, UniqueArray(resource)) | | AMS::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource
| resource | String(type), String(id),<br>attributes, relationships,<br>links, meta | type, id | AM::S::Adapter::JsonApi#primary_data_for | resource | String(type), String(id),<br>attributes, relationships,<br>links, meta | type, id | AM::S::Adapter::JsonApi#primary_data_for
| links | Uri(self), Link(related) | | #1028, #1246, #1282 | links | Uri(self), Link(related) | | #1028, #1246, #1282
| link | oneOf (linkString, linkObject) | | | link | oneOf (linkString, linkObject) | |
| link.linkString | Uri | | | link.linkString | Uri | |
| link.linkObject | Uri(href), meta | href | | link.linkObject | Uri(href), meta | href |
| attributes | patternProperties(<br>`"^(?!relationships$|links$)\\w[-\\w_]*$"`),<br>any valid JSON | | AM::Serializer#attributes, AM::S::Adapter::JsonApi#resource_object_for | attributes | patternProperties(<br>`"^(?!relationships$|links$)\\w[-\\w_]*$"`),<br>any valid JSON | | AM::Serializer#attributes, AMS::Adapter::JsonApi#resource_object_for
| relationships | patternProperties(<br>`"^\\w[-\\w_]*$"`);<br>links, relationships.data, meta | | AM::S::Adapter::JsonApi#relationships_for | relationships | patternProperties(<br>`"^\\w[-\\w_]*$"`);<br>links, relationships.data, meta | | AMS::Adapter::JsonApi#relationships_for
| relationships.data | oneOf (relationshipToOne, relationshipToMany) | | AM::S::Adapter::JsonApi#resource_identifier_for | relationships.data | oneOf (relationshipToOne, relationshipToMany) | | AMS::Adapter::JsonApi#resource_identifier_for
| relationshipToOne | anyOf(empty, linkage) | | | relationshipToOne | anyOf(empty, linkage) | |
| relationshipToMany | UniqueArray(linkage) | | | relationshipToMany | UniqueArray(linkage) | |
| empty | null | | | empty | null | |
| linkage | String(type), String(id), meta | type, id | AM::S::Adapter::JsonApi#primary_data_for | linkage | String(type), String(id), meta | type, id | AMS::Adapter::JsonApi#primary_data_for
| pagination | pageObject(first), pageObject(last),<br>pageObject(prev), pageObject(next) | | AM::S::Adapter::JsonApi::PaginationLinks#serializable_hash | pagination | pageObject(first), pageObject(last),<br>pageObject(prev), pageObject(next) | | AMS::Adapter::JsonApi::PaginationLinks#serializable_hash
| pagination.pageObject | oneOf(Uri, null) | | | pagination.pageObject | oneOf(Uri, null) | |
| jsonapi | String(version), meta | | AM::S::Adapter::JsonApi::ApiObjects::JsonApi | jsonapi | String(version), meta | | AMS::Adapter::JsonApi::ApiObjects::JsonApi#as_json
| error | String(id), links, String(status),<br>String(code), String(title),<br>String(detail), error.source, meta | | | error | String(id), links, String(status),<br>String(code), String(title),<br>String(detail), error.source, meta | | AM::S::ErrorSerializer, AMS::Adapter::JsonApi::Error.resource_errors
| error.source | String(pointer), String(parameter) | | | error.source | String(pointer), String(parameter) | | AMS::Adapter::JsonApi::Error.error_source
| pointer | [JSON Pointer RFC6901](https://tools.ietf.org/html/rfc6901) | | | pointer | [JSON Pointer RFC6901](https://tools.ietf.org/html/rfc6901) | | AMS::JsonPointer
The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap. The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
@ -102,7 +102,7 @@ The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
### Failure Document ### Failure Document
- [ ] failure - [ ] failure
- [ ] errors: array of unique items of type ` "$ref": "#/definitions/error"` - [x] errors: array of unique items of type ` "$ref": "#/definitions/error"`
- [ ] meta: `"$ref": "#/definitions/meta"` - [ ] meta: `"$ref": "#/definitions/meta"`
- [ ] jsonapi: `"$ref": "#/definitions/jsonapi"` - [ ] jsonapi: `"$ref": "#/definitions/jsonapi"`
@ -137,4 +137,15 @@ The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
- [ ] pagination - [ ] pagination
- [ ] jsonapi - [ ] jsonapi
- [ ] meta - [ ] meta
- [ ] error: id, links, status, code, title: detail: source [{pointer, type}, {parameter: {description, type}], meta - [ ] error
- [ ] id: a unique identifier for this particular occurrence of the problem.
- [ ] links: a links object containing the following members:
- [ ] about: a link that leads to further details about this particular occurrence of the problem.
- [ ] status: the HTTP status code applicable to this problem, expressed as a string value.
- [ ] code: an application-specific error code, expressed as a string value.
- [ ] title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
- [x] detail: a human-readable explanation specific to this occurrence of the problem.
- [x] source: an object containing references to the source of the error, optionally including any of the following members:
- [x] pointer: a JSON Pointer [RFC6901](https://tools.ietf.org/html/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].
- [x] parameter: a string indicating which query parameter caused the error.
- [ ] meta: a meta object containing non-standard meta-information about the error.

4
lib/active_model/serializer/adapter/json_api/api_objects/relationship.rb
View File

@ -4,6 +4,10 @@ module ActiveModel
class JsonApi class JsonApi
module ApiObjects module ApiObjects
class Relationship class Relationship
# {http://jsonapi.org/format/#document-resource-object-related-resource-links Document Resource Object Related Resource Links}
# {http://jsonapi.org/format/#document-links Document Links}
# {http://jsonapi.org/format/#document-resource-object-linkage Document Resource Relationship Linkage}
# {http://jsonapi.org/format/#document-meta Docment Meta}
def initialize(parent_serializer, serializer, options = {}, links = {}, meta = nil) def initialize(parent_serializer, serializer, options = {}, links = {}, meta = nil)
@object = parent_serializer.object @object = parent_serializer.object
@scope = parent_serializer.scope @scope = parent_serializer.scope

1
lib/active_model/serializer/adapter/json_api/api_objects/resource_identifier.rb
View File

@ -4,6 +4,7 @@ module ActiveModel
class JsonApi class JsonApi
module ApiObjects module ApiObjects
class ResourceIdentifier class ResourceIdentifier
# {http://jsonapi.org/format/#document-resource-identifier-objects Resource Identifier Objects}
def initialize(serializer) def initialize(serializer)
@id = id_for(serializer) @id = id_for(serializer)
@type = type_for(serializer) @type = type_for(serializer)

12
lib/active_model_serializers/adapter/json_api.rb
View File

@ -13,6 +13,7 @@ module ActiveModelSerializers
# TODO: if we like this abstraction and other API objects to it, # TODO: if we like this abstraction and other API objects to it,
# then extract to its own file and require it. # then extract to its own file and require it.
module ApiObjects module ApiObjects
# {http://jsonapi.org/format/#document-jsonapi-object Jsonapi Object}
module Jsonapi module Jsonapi
ActiveModelSerializers.config.jsonapi_version = '1.0' ActiveModelSerializers.config.jsonapi_version = '1.0'
ActiveModelSerializers.config.jsonapi_toplevel_meta = {} ActiveModelSerializers.config.jsonapi_toplevel_meta = {}
@ -51,6 +52,8 @@ module ActiveModelSerializers
@fieldset = options[:fieldset] || ActiveModel::Serializer::Fieldset.new(options.delete(:fields)) @fieldset = options[:fieldset] || ActiveModel::Serializer::Fieldset.new(options.delete(:fields))
end end
# {http://jsonapi.org/format/#crud Requests are transactional, i.e. success or failure}
# {http://jsonapi.org/format/#document-top-level data and errors MUST NOT coexist in the same document.}
def serializable_hash(options = nil) def serializable_hash(options = nil)
options ||= {} options ||= {}
if serializer.success? if serializer.success?
@ -60,6 +63,7 @@ module ActiveModelSerializers
end end
end end
# {http://jsonapi.org/format/#document-top-level Primary data}
def success_document(options) def success_document(options)
is_collection = serializer.respond_to?(:each) is_collection = serializer.respond_to?(:each)
serializers = is_collection ? serializer : [serializer] serializers = is_collection ? serializer : [serializer]
@ -84,6 +88,7 @@ module ActiveModelSerializers
hash hash
end end
# {http://jsonapi.org/format/#errors JSON API Errors}
# TODO: look into caching # TODO: look into caching
# rubocop:disable Style/AsciiComments # rubocop:disable Style/AsciiComments
# definition: # definition:
@ -117,6 +122,7 @@ module ActiveModelSerializers
private private
# {http://jsonapi.org/format/#document-resource-objects Primary data}
def resource_objects_for(serializers) def resource_objects_for(serializers)
@primary = [] @primary = []
@included = [] @included = []
@ -158,10 +164,12 @@ module ActiveModelSerializers
process_relationships(serializer, include_tree) process_relationships(serializer, include_tree)
end end
# {http://jsonapi.org/format/#document-resource-object-attributes Document Resource Object Attributes}
def attributes_for(serializer, fields) def attributes_for(serializer, fields)
serializer.attributes(fields).except(:id) serializer.attributes(fields).except(:id)
end end
# {http://jsonapi.org/format/#document-resource-objects Document Resource Objects}
def resource_object_for(serializer) def resource_object_for(serializer)
resource_object = cache_check(serializer) do resource_object = cache_check(serializer) do
resource_object = ActiveModel::Serializer::Adapter::JsonApi::ApiObjects::ResourceIdentifier.new(serializer).as_json resource_object = ActiveModel::Serializer::Adapter::JsonApi::ApiObjects::ResourceIdentifier.new(serializer).as_json
@ -185,6 +193,7 @@ module ActiveModelSerializers
resource_object resource_object
end end
# {http://jsonapi.org/format/#document-resource-object-relationships Document Resource Object Relationship}
def relationships_for(serializer, requested_associations) def relationships_for(serializer, requested_associations)
include_tree = ActiveModel::Serializer::IncludeTree.from_include_args(requested_associations) include_tree = ActiveModel::Serializer::IncludeTree.from_include_args(requested_associations)
serializer.associations(include_tree).each_with_object({}) do |association, hash| serializer.associations(include_tree).each_with_object({}) do |association, hash|
@ -198,16 +207,19 @@ module ActiveModelSerializers
end end
end end
# {http://jsonapi.org/format/#document-links Document Links}
def links_for(serializer) def links_for(serializer)
serializer._links.each_with_object({}) do |(name, value), hash| serializer._links.each_with_object({}) do |(name, value), hash|
hash[name] = Link.new(serializer, value).as_json hash[name] = Link.new(serializer, value).as_json
end end
end end
# {http://jsonapi.org/format/#fetching-pagination Pagination Links}
def pagination_links_for(serializer, options) def pagination_links_for(serializer, options)
JsonApi::PaginationLinks.new(serializer.object, options[:serialization_context]).serializable_hash(options) JsonApi::PaginationLinks.new(serializer.object, options[:serialization_context]).serializable_hash(options)
end end
# {http://jsonapi.org/format/#document-meta Docment Meta}
def meta_for(serializer) def meta_for(serializer)
ActiveModel::Serializer::Adapter::JsonApi::Meta.new(serializer).as_json ActiveModel::Serializer::Adapter::JsonApi::Meta.new(serializer).as_json
end end