Added more detailed examples to deserialization.md from json_api/deserialization.rb

docs/general/deserialization.md

@@ -15,7 +15,7 @@ The `ActiveModelSerializers::Deserialization` defines two methods (namely `jsona
     - except: `Array` of blacklisted fields
     - keys: `Hash` of fields the name of which needs to be modified (e.g. `{ :author => :user, :date => :created_at }`)
 
-Example:
+Examples:
 
 ```ruby
 class PostsController < ActionController::Base
@@ -29,6 +29,72 @@ class PostsController < ActionController::Base
 end
 ```
 
+
+
+Given a JSON API document,
+
+```
+document = {
+  data: {
+    id: 1,
+    type: 'post',
+    attributes: {
+      title: 'Title 1',
+      date: '2015-12-20'
+    },
+    associations: {
+      author: {
+        data: {
+          type: 'user',
+          id: 2
+        }
+      },
+      second_author: {
+        data: nil
+      },
+      comments: {
+        data: [{
+          type: 'comment',
+          id: 3
+        },{
+          type: 'comment',
+          id: 4
+        }]
+      }
+    }
+  }
+}
+```
+
+The entire document can be parsed without specifying any options:
+```ruby
+ActiveModelSerializers::Deserialization.jsonapi_parse(document)
+#=>
+# {
+#   title: 'Title 1',
+#   date: '2015-12-20',
+#   author_id: 2,
+#   second_author_id: nil
+#   comment_ids: [3, 4]
+# }
+```
+
+and fields, relationships, and polymorphic relationships can be specified via the options:
+
+```ruby
+ActiveModelSerializers::Deserialization
+  .jsonapi_parse(document, only: [:title, :date, :author],
+                           keys: { date: :published_at },
+                           polymorphic: [:author])
+#=>
+# {
+#   title: 'Title 1',
+#   published_at: '2015-12-20',
+#   author_id: '2',
+#   author_type: 'user'
+# }
+```
+
 ## Attributes/Json
 
 There is currently no deserialization for those adapters.