docs/general/adapters.md in active_model_serializers-0.10.0.rc4 vs docs/general/adapters.md in active_model_serializers-0.10.0.rc5
- old
+ new
@@ -9,11 +9,11 @@
It should be set only once, preferably at initialization.
For example:
```ruby
-ActiveModelSerializers.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
+ActiveModelSerializers.config.adapter = ActiveModelSerializers::Adapter::JsonApi
```
or
```ruby
@@ -41,23 +41,106 @@
### Attributes - Default
It's the default adapter, it generates a json response without a root key.
Doesn't follow any specific convention.
+##### Example output
+
+```json
+{
+ "title": "Title 1",
+ "body": "Body 1",
+ "publish_at": "2020-03-16T03:55:25.291Z",
+ "author": {
+ "first_name": "Bob",
+ "last_name": "Jones"
+ },
+ "comments": [
+ {
+ "body": "cool"
+ },
+ {
+ "body": "awesome"
+ }
+ ]
+}
+```
+
### JSON
The response document always with a root key.
The root key **can't be overridden**, and will be derived from the resource being serialized.
Doesn't follow any specific convention.
+##### Example output
+
+```json
+{
+ "post": {
+ "title": "Title 1",
+ "body": "Body 1",
+ "publish_at": "2020-03-16T03:55:25.291Z",
+ "author": {
+ "first_name": "Bob",
+ "last_name": "Jones"
+ },
+ "comments": [{
+ "body": "cool"
+ }, {
+ "body": "awesome"
+ }]
+ }
+}
+```
+
### JSON API
This adapter follows **version 1.0** of the [format specified](../jsonapi/schema.md) in
[jsonapi.org/format](http://jsonapi.org/format).
+##### Example output
+
+```json
+{
+ "data": {
+ "id": "1337",
+ "type": "posts",
+ "attributes": {
+ "title": "Title 1",
+ "body": "Body 1",
+ "publish-at": "2020-03-16T03:55:25.291Z"
+ },
+ "relationships": {
+ "author": {
+ "data": {
+ "id": "1",
+ "type": "authors"
+ }
+ },
+ "comments": {
+ "data": [{
+ "id": "7",
+ "type": "comments"
+ }, {
+ "id": "12",
+ "type": "comments"
+ }]
+ }
+ },
+ "links": {
+ "post-authors": "https://example.com/post_authors"
+ },
+ "meta": {
+ "rating": 5,
+ "favorite-count": 10
+ }
+ }
+}
+```
+
#### Included
It will include the associated resources in the `"included"` member
when the resource names are included in the `include` option.
Including nested associated resources is also supported.
@@ -115,48 +198,48 @@
The default adapter can be configured, as above, to use any class given to it.
An adapter may also be specified, e.g. when rendering, as a class or as a symbol.
If a symbol, then the adapter must be, e.g. `:great_example`,
-`ActiveModel::Serializer::Adapter::GreatExample`, or registered.
+`ActiveModelSerializers::Adapter::GreatExample`, or registered.
There are two ways to register an adapter:
-1) The simplest, is to subclass `ActiveModel::Serializer::Adapter`, e.g. the below will
-register the `Example::UsefulAdapter` as `:useful_adapter`.
+1) The simplest, is to subclass `ActiveModelSerializers::Adapter::Base`, e.g. the below will
+register the `Example::UsefulAdapter` as `"example/useful_adapter"`.
```ruby
module Example
- class UsefulAdapter < ActiveModel::Serializer::Adapter
+ class UsefulAdapter < ActiveModelSerializers::Adapter::Base
end
end
```
-You'll notice that the name it registers is the class name underscored, not the full namespace.
+You'll notice that the name it registers is the underscored namespace and class.
-Under the covers, when the `ActiveModel::Serializer::Adapter` is subclassed, it registers
-the subclass as `register(:useful_adapter, Example::UsefulAdapter)`
+Under the covers, when the `ActiveModelSerializers::Adapter::Base` is subclassed, it registers
+the subclass as `register("example/useful_adapter", Example::UsefulAdapter)`
2) Any class can be registered as an adapter by calling `register` directly on the
-`ActiveModel::Serializer::Adapter` class. e.g., the below registers `MyAdapter` as
+`ActiveModelSerializers::Adapter` class. e.g., the below registers `MyAdapter` as
`:special_adapter`.
```ruby
class MyAdapter; end
-ActiveModel::Serializer::Adapter.register(:special_adapter, MyAdapter)
+ActiveModelSerializers::Adapter.register(:special_adapter, MyAdapter)
```
### Looking up an adapter
| Method | Return value |
| :------------ |:---------------|
-| `ActiveModel::Serializer::Adapter.adapter_map` | A Hash of all known adapters `{ adapter_name => adapter_class }` |
-| `ActiveModel::Serializer::Adapter.adapters` | A (sorted) Array of all known `adapter_names` |
-| `ActiveModel::Serializer::Adapter.lookup(name_or_klass)` | The `adapter_class`, else raises an `ActiveModel::Serializer::Adapter::UnknownAdapter` error |
-| `ActiveModel::Serializer::Adapter.adapter_class(adapter)` | Delegates to `ActiveModel::Serializer::Adapter.lookup(adapter)` |
-| `ActiveModel::Serializer.adapter` | A convenience method for `ActiveModel::Serializer::Adapter.lookup(config.adapter)` |
+| `ActiveModelSerializers::Adapter.adapter_map` | A Hash of all known adapters `{ adapter_name => adapter_class }` |
+| `ActiveModelSerializers::Adapter.adapters` | A (sorted) Array of all known `adapter_names` |
+| `ActiveModelSerializers::Adapter.lookup(name_or_klass)` | The `adapter_class`, else raises an `ActiveModelSerializers::Adapter::UnknownAdapter` error |
+| `ActiveModelSerializers::Adapter.adapter_class(adapter)` | Delegates to `ActiveModelSerializers::Adapter.lookup(adapter)` |
+| `ActiveModelSerializers::Adapter.configured_adapter` | A convenience method for `ActiveModelSerializers::Adapter.lookup(config.adapter)` |
The registered adapter name is always a String, but may be looked up as a Symbol or String.
Helpfully, the Symbol or String is underscored, so that `get(:my_adapter)` and `get("MyAdapter")`
may both be used.
-For more information, see [the Adapter class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer/adapter.rb)
+For more information, see [the Adapter class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/adapter.rb)