Skip to content

Commit e6ae34b

Browse files
bf4bf4
committed
Update documentation with Yard links
1 parent 3d98637 commit e6ae34b

File tree

6 files changed

+50
-19
lines changed

6 files changed

+50
-19
lines changed

‎CHANGELOG.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
Breaking changes:
44

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

‎docs/jsonapi/errors.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[Back to Guides](../README.md)
22

3-
# JSON API Errors
3+
# [JSON API Errors](http://jsonapi.org/format/#errors)
44

55
Rendering error documents requires specifying the error serializer(s):
66

‎docs/jsonapi/schema.md

Lines changed: 29 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -58,33 +58,33 @@ Example supported requests
5858
|-----------------------|----------------------------------------------------------------------------------------------------|----------|---------------------------------------|
5959
| schema | oneOf (success, failure, info) | |
6060
| success | data, included, meta, links, jsonapi | | AM::SerializableResource
61-
| success.meta | meta | | AM::S::Adapter::Base#meta
62-
| success.included | UniqueArray(resource) | | AM::S::Adapter::JsonApi#serializable_hash_for_collection
61+
| success.meta | meta | | AMS::Adapter::Base#meta
62+
| success.included | UniqueArray(resource) | | AMS::Adapter::JsonApi#serializable_hash_for_collection
6363
| success.data | data | |
64-
| success.links | allOf (links, pagination) | | AM::S::Adapter::JsonApi#links_for
64+
| success.links | allOf (links, pagination) | | AMS::Adapter::JsonApi#links_for
6565
| success.jsonapi | jsonapi | |
66-
| failure | errors, meta, jsonapi | errors |
67-
| failure.errors | UniqueArray(error) | | #1004
68-
| meta | Object | |
69-
| data | oneOf (resource, UniqueArray(resource)) | | AM::S::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource
66+
| failure | errors, meta, jsonapi | errors | AMS::Adapter::JsonApi#failure_document, #1004
67+
| failure.errors | UniqueArray(error) | | AM::S::ErrorSerializer, #1004
68+
| meta | Object | |
69+
| data | oneOf (resource, UniqueArray(resource)) | | AMS::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource
7070
| resource | String(type), String(id),<br>attributes, relationships,<br>links, meta | type, id | AM::S::Adapter::JsonApi#primary_data_for
7171
| links | Uri(self), Link(related) | | #1028, #1246, #1282
7272
| link | oneOf (linkString, linkObject) | |
7373
| link.linkString | Uri | |
7474
| link.linkObject | Uri(href), meta | href |
75-
| attributes | patternProperties(<br>`"^(?!relationships$|links$)\\w[-\\w_]*$"`),<br>any valid JSON | | AM::Serializer#attributes, AM::S::Adapter::JsonApi#resource_object_for
76-
| relationships | patternProperties(<br>`"^\\w[-\\w_]*$"`);<br>links, relationships.data, meta | | AM::S::Adapter::JsonApi#relationships_for
77-
| relationships.data | oneOf (relationshipToOne, relationshipToMany) | | AM::S::Adapter::JsonApi#resource_identifier_for
75+
| attributes | patternProperties(<br>`"^(?!relationships$|links$)\\w[-\\w_]*$"`),<br>any valid JSON | | AM::Serializer#attributes, AMS::Adapter::JsonApi#resource_object_for
76+
| relationships | patternProperties(<br>`"^\\w[-\\w_]*$"`);<br>links, relationships.data, meta | | AMS::Adapter::JsonApi#relationships_for
77+
| relationships.data | oneOf (relationshipToOne, relationshipToMany) | | AMS::Adapter::JsonApi#resource_identifier_for
7878
| relationshipToOne | anyOf(empty, linkage) | |
7979
| relationshipToMany | UniqueArray(linkage) | |
8080
| empty | null | |
81-
| linkage | String(type), String(id), meta | type, id | AM::S::Adapter::JsonApi#primary_data_for
82-
| pagination | pageObject(first), pageObject(last),<br>pageObject(prev), pageObject(next) | | AM::S::Adapter::JsonApi::PaginationLinks#serializable_hash
81+
| linkage | String(type), String(id), meta | type, id | AMS::Adapter::JsonApi#primary_data_for
82+
| pagination | pageObject(first), pageObject(last),<br>pageObject(prev), pageObject(next) | | AMS::Adapter::JsonApi::PaginationLinks#serializable_hash
8383
| pagination.pageObject | oneOf(Uri, null) | |
84-
| jsonapi | String(version), meta | | AM::S::Adapter::JsonApi::ApiObjects::JsonApi
85-
| error | String(id), links, String(status),<br>String(code), String(title),<br>String(detail), error.source, meta | |
86-
| error.source | String(pointer), String(parameter) | |
87-
| pointer | [JSON Pointer RFC6901](https://tools.ietf.org/html/rfc6901) | |
84+
| jsonapi | String(version), meta | | AMS::Adapter::JsonApi::ApiObjects::JsonApi#as_json
85+
| 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
86+
| error.source | String(pointer), String(parameter) | | AMS::Adapter::JsonApi::Error.error_source
87+
| pointer | [JSON Pointer RFC6901](https://tools.ietf.org/html/rfc6901) | | AMS::JsonPointer
8888

8989

9090
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.
102102
### Failure Document
103103

104104
- [ ] failure
105-
- [ ] errors: array of unique items of type ` "$ref": "#/definitions/error"`
105+
- [x] errors: array of unique items of type ` "$ref": "#/definitions/error"`
106106
- [ ] meta: `"$ref": "#/definitions/meta"`
107107
- [ ] jsonapi: `"$ref": "#/definitions/jsonapi"`
108108

@@ -137,4 +137,15 @@ The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
137137
- [ ] pagination
138138
- [ ] jsonapi
139139
- [ ] meta
140-
- [ ] error: id, links, status, code, title: detail: source [{pointer, type}, {parameter: {description, type}], meta
140+
- [ ] error
141+
- [ ] id: a unique identifier for this particular occurrence of the problem.
142+
- [ ] links: a links object containing the following members:
143+
- [ ] about: a link that leads to further details about this particular occurrence of the problem.
144+
- [ ] status: the HTTP status code applicable to this problem, expressed as a string value.
145+
- [ ] code: an application-specific error code, expressed as a string value.
146+
- [ ] 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.
147+
- [x] detail: a human-readable explanation specific to this occurrence of the problem.
148+
- [x] source: an object containing references to the source of the error, optionally including any of the following members:
149+
- [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].
150+
- [x] parameter: a string indicating which query parameter caused the error.
151+
- [ ] meta: a meta object containing non-standard meta-information about the error.

‎lib/active_model/serializer/adapter/json_api/api_objects/relationship.rb

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ module Adapter
44
class JsonApi
55
module ApiObjects
66
class Relationship
7+
# {http://jsonapi.org/format/#document-resource-object-related-resource-links Document Resource Object Related Resource Links}
8+
# {http://jsonapi.org/format/#document-links Document Links}
9+
# {http://jsonapi.org/format/#document-resource-object-linkage Document Resource Relationship Linkage}
10+
# {http://jsonapi.org/format/#document-meta Docment Meta}
711
def initialize(parent_serializer, serializer, options = {}, links = {}, meta = nil)
812
@object = parent_serializer.object
913
@scope = parent_serializer.scope

‎lib/active_model/serializer/adapter/json_api/api_objects/resource_identifier.rb

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ module Adapter
44
class JsonApi
55
module ApiObjects
66
class ResourceIdentifier
7+
# {http://jsonapi.org/format/#document-resource-identifier-objects Resource Identifier Objects}
78
def initialize(serializer)
89
@id = id_for(serializer)
910
@type = type_for(serializer)

‎lib/active_model_serializers/adapter/json_api.rb

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ class JsonApi < Base
1313
# TODO: if we like this abstraction and other API objects to it,
1414
# then extract to its own file and require it.
1515
module ApiObjects
16+
# {http://jsonapi.org/format/#document-jsonapi-object Jsonapi Object}
1617
module Jsonapi
1718
ActiveModelSerializers.config.jsonapi_version = '1.0'
1819
ActiveModelSerializers.config.jsonapi_toplevel_meta = {}
@@ -51,6 +52,8 @@ def initialize(serializer, options = {})
5152
@fieldset = options[:fieldset] || ActiveModel::Serializer::Fieldset.new(options.delete(:fields))
5253
end
5354

55+
# {http://jsonapi.org/format/#crud Requests are transactional, i.e. success or failure}
56+
# {http://jsonapi.org/format/#document-top-level data and errors MUST NOT coexist in the same document.}
5457
def serializable_hash(options = nil)
5558
options ||= {}
5659
if serializer.success?
@@ -60,6 +63,7 @@ def serializable_hash(options = nil)
6063
end
6164
end
6265

66+
# {http://jsonapi.org/format/#document-top-level Primary data}
6367
def success_document(options)
6468
is_collection = serializer.respond_to?(:each)
6569
serializers = is_collection ? serializer : [serializer]
@@ -84,6 +88,7 @@ def success_document(options)
8488
hash
8589
end
8690

91+
# {http://jsonapi.org/format/#errors JSON API Errors}
8792
# TODO: look into caching
8893
# rubocop:disable Style/AsciiComments
8994
# definition:
@@ -117,6 +122,7 @@ def fragment_cache(cached_hash, non_cached_hash)
117122

118123
private
119124

125+
# {http://jsonapi.org/format/#document-resource-objects Primary data}
120126
def resource_objects_for(serializers)
121127
@primary = []
122128
@included = []
@@ -158,10 +164,12 @@ def process_relationship(serializer, include_tree)
158164
process_relationships(serializer, include_tree)
159165
end
160166

167+
# {http://jsonapi.org/format/#document-resource-object-attributes Document Resource Object Attributes}
161168
def attributes_for(serializer, fields)
162169
serializer.attributes(fields).except(:id)
163170
end
164171

172+
# {http://jsonapi.org/format/#document-resource-objects Document Resource Objects}
165173
def resource_object_for(serializer)
166174
resource_object = cache_check(serializer) do
167175
resource_object = ActiveModel::Serializer::Adapter::JsonApi::ApiObjects::ResourceIdentifier.new(serializer).as_json
@@ -185,6 +193,7 @@ def resource_object_for(serializer)
185193
resource_object
186194
end
187195

196+
# {http://jsonapi.org/format/#document-resource-object-relationships Document Resource Object Relationship}
188197
def relationships_for(serializer, requested_associations)
189198
include_tree = ActiveModel::Serializer::IncludeTree.from_include_args(requested_associations)
190199
serializer.associations(include_tree).each_with_object({}) do |association, hash|
@@ -198,16 +207,19 @@ def relationships_for(serializer, requested_associations)
198207
end
199208
end
200209

210+
# {http://jsonapi.org/format/#document-links Document Links}
201211
def links_for(serializer)
202212
serializer._links.each_with_object({}) do |(name, value), hash|
203213
hash[name] = Link.new(serializer, value).as_json
204214
end
205215
end
206216

217+
# {http://jsonapi.org/format/#fetching-pagination Pagination Links}
207218
def pagination_links_for(serializer, options)
208219
JsonApi::PaginationLinks.new(serializer.object, options[:serialization_context]).serializable_hash(options)
209220
end
210221

222+
# {http://jsonapi.org/format/#document-meta Docment Meta}
211223
def meta_for(serializer)
212224
ActiveModel::Serializer::Adapter::JsonApi::Meta.new(serializer).as_json
213225
end

0 commit comments

Comments
 (0)