media_types-serialization 1.2.0 → 1.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c72aa611b03ba3537f1c12eb44b31596f58d21ba3fe0dd5596b8d37d613d132
-  data.tar.gz: '084a4733e9d015fe1816399772d3fcfaed898368507d9785df89bdb296b34171'
+  metadata.gz: 737a38bc10cd0c3aff8fa9bc33c3c192098709eb331f7c35706840410ff3d280
+  data.tar.gz: d6311d9a1b27329e4164cb7bf3b8e839ce96419b05e9a9e42d033d7ba2942a50
 SHA512:
-  metadata.gz: 67d43c2377d4ac849997886fa547d9b6c22ee7880eca6e1acfebd73db3cbe18a189823ca79bec0a009ab2feb83aa6b7d2d4a7e50ac44e9e0f37207fe4c07bb87
-  data.tar.gz: 2d9825fca6e6d77f84609b691d5dcd113424b41adf971efe87fe7bcd56220dd34a6aaec6a7ce905474131ed398e5fed8decf11f4e2209752b3a9cfbfbd80933f
+  metadata.gz: c6fad7b09ecc516290fb5e0393ee5a790c128a75402cdb977c396b6dac01b30748b63f5631b001b7eaa9d9c1b8007e814200d9be7766afa757d1c93785bc34f8
+  data.tar.gz: ea95bb41414b2125ac3af7efe42ff9c5e521f36a7bae2930760dd52fdee3e58e1175e5aaa8f03d3eb27bf5022d089f0542f4bc51b418cee05ae3724ba3756779

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.3.4
+
+- Same as `1.3.3`
+
+## 1.3.3
+
+- 🐛 Fix override suffix not being picked up correctly
+- 🐛 Fix inability to override suffix for aliases
+- 🐛 Fix inability to override suffix for raw
+- 🐛 Fix default suffix for raw
+
+## 1.3.2
+
+- 🐛 Fix override suffix not returning self or new
+
+## 1.3.1
+
+- 🐛 Fix api viewer
+- 🐛 Fix `output_raw` suffix (`+json` needs to be `''`)
+
+## 1.3.0
+
+- ✨ Add `formats:` to `output_html` and default it to `[:html]`, so rails behaves
+- 🐛 Fix stale references to `render media:`
+- 🐛 Fix inconsistent `context:` passing for `Serializer.serialize`
+
 ## 1.2.0
 
 - ✨ Add `view:` to `output_html` which renders a specific rails view.

data/Gemfile.lock

@@ -1,137 +1,137 @@
-PATH
-  remote: .
-  specs:
-    media_types-serialization (1.1.0)
-      actionpack (>= 4.0.0)
-      activesupport (>= 4.0.0)
-      media_types (>= 2.0.0, < 3.0.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    actioncable (5.2.6)
-      actionpack (= 5.2.6)
-      nio4r (~> 2.0)
-      websocket-driver (>= 0.6.1)
-    actionmailer (5.2.6)
-      actionpack (= 5.2.6)
-      actionview (= 5.2.6)
-      activejob (= 5.2.6)
-      mail (~> 2.5, >= 2.5.4)
-      rails-dom-testing (~> 2.0)
-    actionpack (5.2.6)
-      actionview (= 5.2.6)
-      activesupport (= 5.2.6)
-      rack (~> 2.0, >= 2.0.8)
-      rack-test (>= 0.6.3)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (5.2.6)
-      activesupport (= 5.2.6)
-      builder (~> 3.1)
-      erubi (~> 1.4)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.3)
-    activejob (5.2.6)
-      activesupport (= 5.2.6)
-      globalid (>= 0.3.6)
-    activemodel (5.2.6)
-      activesupport (= 5.2.6)
-    activerecord (5.2.6)
-      activemodel (= 5.2.6)
-      activesupport (= 5.2.6)
-      arel (>= 9.0)
-    activestorage (5.2.6)
-      actionpack (= 5.2.6)
-      activerecord (= 5.2.6)
-      marcel (~> 1.0.0)
-    activesupport (5.2.6)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-    arel (9.0.0)
-    awesome_print (1.9.2)
-    builder (3.2.4)
-    concurrent-ruby (1.1.9)
-    crass (1.0.6)
-    erubi (1.10.0)
-    globalid (0.4.2)
-      activesupport (>= 4.2.0)
-    i18n (1.8.10)
-      concurrent-ruby (~> 1.0)
-    loofah (2.10.0)
-      crass (~> 1.0.2)
-      nokogiri (>= 1.5.9)
-    mail (2.7.1)
-      mini_mime (>= 0.1.1)
-    marcel (1.0.1)
-    media_types (2.0.1)
-    method_source (1.0.0)
-    mini_mime (1.1.0)
-    minitest (5.14.4)
-    nio4r (2.5.7)
-    nokogiri (1.11.7-x64-mingw32)
-      racc (~> 1.4)
-    nokogiri (1.11.7-x86_64-linux)
-      racc (~> 1.4)
-    oj (3.12.1)
-    racc (1.5.2)
-    rack (2.2.3)
-    rack-test (1.1.0)
-      rack (>= 1.0, < 3)
-    rails (5.2.6)
-      actioncable (= 5.2.6)
-      actionmailer (= 5.2.6)
-      actionpack (= 5.2.6)
-      actionview (= 5.2.6)
-      activejob (= 5.2.6)
-      activemodel (= 5.2.6)
-      activerecord (= 5.2.6)
-      activestorage (= 5.2.6)
-      activesupport (= 5.2.6)
-      bundler (>= 1.3.0)
-      railties (= 5.2.6)
-      sprockets-rails (>= 2.0.0)
-    rails-dom-testing (2.0.3)
-      activesupport (>= 4.2.0)
-      nokogiri (>= 1.6)
-    rails-html-sanitizer (1.3.0)
-      loofah (~> 2.3)
-    railties (5.2.6)
-      actionpack (= 5.2.6)
-      activesupport (= 5.2.6)
-      method_source
-      rake (>= 0.8.7)
-      thor (>= 0.19.0, < 2.0)
-    rake (13.0.6)
-    sprockets (4.0.2)
-      concurrent-ruby (~> 1.0)
-      rack (> 1, < 3)
-    sprockets-rails (3.2.2)
-      actionpack (>= 4.0)
-      activesupport (>= 4.0)
-      sprockets (>= 3.0.0)
-    thor (1.1.0)
-    thread_safe (0.3.6)
-    tzinfo (1.2.9)
-      thread_safe (~> 0.1)
-    websocket-driver (0.7.5)
-      websocket-extensions (>= 0.1.0)
-    websocket-extensions (0.1.5)
-
-PLATFORMS
-  x64-mingw32
-  x86_64-linux
-
-DEPENDENCIES
-  awesome_print
-  bundler
-  media_types-serialization!
-  minitest (~> 5.0)
-  oj
-  rails (~> 5.2)
-  rake (~> 13.0)
-
-BUNDLED WITH
-   2.2.7
+PATH
+  remote: .
+  specs:
+    media_types-serialization (1.3.4)
+      actionpack (>= 4.0.0)
+      activesupport (>= 4.0.0)
+      media_types (>= 2.1.0, < 3.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (5.2.6)
+      actionpack (= 5.2.6)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailer (5.2.6)
+      actionpack (= 5.2.6)
+      actionview (= 5.2.6)
+      activejob (= 5.2.6)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (5.2.6)
+      actionview (= 5.2.6)
+      activesupport (= 5.2.6)
+      rack (~> 2.0, >= 2.0.8)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.2.6)
+      activesupport (= 5.2.6)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activejob (5.2.6)
+      activesupport (= 5.2.6)
+      globalid (>= 0.3.6)
+    activemodel (5.2.6)
+      activesupport (= 5.2.6)
+    activerecord (5.2.6)
+      activemodel (= 5.2.6)
+      activesupport (= 5.2.6)
+      arel (>= 9.0)
+    activestorage (5.2.6)
+      actionpack (= 5.2.6)
+      activerecord (= 5.2.6)
+      marcel (~> 1.0.0)
+    activesupport (5.2.6)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    arel (9.0.0)
+    awesome_print (1.9.2)
+    builder (3.2.4)
+    concurrent-ruby (1.1.9)
+    crass (1.0.6)
+    erubi (1.10.0)
+    globalid (0.5.2)
+      activesupport (>= 5.0)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
+    loofah (2.12.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (1.0.1)
+    media_types (2.1.0)
+    method_source (1.0.0)
+    mini_mime (1.1.0)
+    minitest (5.14.4)
+    nio4r (2.5.8)
+    nokogiri (1.12.3-x64-mingw32)
+      racc (~> 1.4)
+    nokogiri (1.12.3-x86_64-linux)
+      racc (~> 1.4)
+    oj (3.13.1)
+    racc (1.5.2)
+    rack (2.2.3)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (5.2.6)
+      actioncable (= 5.2.6)
+      actionmailer (= 5.2.6)
+      actionpack (= 5.2.6)
+      actionview (= 5.2.6)
+      activejob (= 5.2.6)
+      activemodel (= 5.2.6)
+      activerecord (= 5.2.6)
+      activestorage (= 5.2.6)
+      activesupport (= 5.2.6)
+      bundler (>= 1.3.0)
+      railties (= 5.2.6)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.3.0)
+      loofah (~> 2.3)
+    railties (5.2.6)
+      actionpack (= 5.2.6)
+      activesupport (= 5.2.6)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.19.0, < 2.0)
+    rake (13.0.6)
+    sprockets (4.0.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.2)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    thor (1.1.0)
+    thread_safe (0.3.6)
+    tzinfo (1.2.9)
+      thread_safe (~> 0.1)
+    websocket-driver (0.7.5)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+
+PLATFORMS
+  x64-mingw32
+  x86_64-linux
+
+DEPENDENCIES
+  awesome_print
+  bundler
+  media_types-serialization!
+  minitest (~> 5.0)
+  oj
+  rails (~> 5.2)
+  rake (~> 13.0)
+
+BUNDLED WITH
+   2.2.7

data/README.md

@@ -79,11 +79,13 @@ class BookController < ActionController::API
 end
 ```
 
-While using the controller integration the context will always be set to the current controller. This allows you to construct urls.
+While using the controller integration the context will always be set to the current controller.
+This allows you to construct urls.
 
 ### Adding HATEOAS responses to existing routes
 
-When creating a mobile application it's often useful to allow the app to request a non-html representation of a specific url. If you have an existing route:
+When creating a mobile application it's often useful to allow the app to request a non-html representation of a specific url.
+If you have an existing route:
 
 ```ruby
 class BookController < ApplicationController
@@ -113,7 +115,9 @@ end
 
 ### Validations
 
-Right now the serializer does not validate incoming or outgoing information. This can cause issues when you accidentally emit non-conforming data that people start to depend on. To make sure you don't do that you can specify a [Media Type validator](https://github.com/SleeplessByte/media-types-ruby):
+Right now the serializer does not validate incoming or outgoing information.
+This can cause issues when you accidentally emit non-conforming data that people start to depend on.
+To make sure you don't do that you can specify a [Media Type validator](https://github.com/SleeplessByte/media-types-ruby):
 
 ```ruby
 require 'media_types'
@@ -179,7 +183,8 @@ BookSerializer.serialize(book, BookValidator.version(2), context: nil)
 
 ### Links
 
-When making [HATEOAS](https://docs.delftsolutions.nl/wiki/HATEOAS_API) compliant applications it's very useful to include `Link` headers in your response so clients can use a `HEAD` request instead of having to fetch the entire resource. Serializers have convenience methods to help with this:
+When making [HATEOAS](https://docs.delftsolutions.nl/wiki/HATEOAS_API) compliant applications it's very useful to include `Link` headers in your response so clients can use a `HEAD` request instead of having to fetch the entire resource.
+Serializers have convenience methods to help with this:
 
 ```ruby
 class BookSerializer < MediaTypes::Serialization::Base
@@ -218,7 +223,8 @@ There are convenience methods for serializing arrays of objects based on a templ
 
 #### Indexes
 
-An index is a collection of urls that point to members of the array. The index method automatically generates it based on the self links defined in the default view of the same version.
+An index is a collection of urls that point to members of the array.
+The index method automatically generates it based on the self links defined in the default view of the same version.
 
 ```ruby
 class BookSerializer < MediaTypes::Serialization::Base
@@ -260,7 +266,8 @@ BookSerializer.serialize([book], BookValidator.view(:index).version(3), context:
 
 #### Collections
 
-A collection inlines the member objects. The collection method automatically generates it based on the default view of the same version.
+A collection inlines the member objects.
+The collection method automatically generates it based on the default view of the same version.
 
 ```ruby
 class BookSerializer < MediaTypes::Serialization::Base
@@ -329,6 +336,7 @@ class BookSerializer < MediaTypes::Serialization::Base
       attribute :title, obj.title
       attribute :description, obj.description if version >= 2
     end
+  end
 
   input version: 3
 end
@@ -344,7 +352,7 @@ class BookController < ActionController::API
     book = Book.new
     book.title = 'Everything, abridged'
 
-    render media: serialize_media(book), content_type: request.format.to_s
+    render_media serialize_media(book)
   end
 
   def create
@@ -390,14 +398,14 @@ class BookController < ActionController::API
     book = Book.new
     book.title = 'Everything, abridged'
 
-    render media: serialize_media(book), content_type: request.format.to_s
+    render_media serialize_media(book)
   end
 
   def create
     book = deserialize(request)
     book.save!
 
-    render media: serialize_media(book), content_type request.format.to_s
+    render_media serialize_media(book)
   end
 end
 ```
@@ -406,7 +414,9 @@ If you don't want to apply any input validation or deserialization you can use t
 
 ### Raw output
 
-Sometimes you need to output raw data. This cannot be validated. You do this as follows:
+Sometimes you need to output raw data.
+This cannot be validated.
+You do this as follows:
 
 ```ruby
 class BookSerializer < MediaTypes::Serialization::Base
@@ -443,7 +453,8 @@ end
 
 ### Remapping media type identifiers
 
-Sometimes you already have old clients using an `application/json` media type identifier when they do requests. While this is not a good practise as this makes it hard to add new fields or remove old ones, this library has support for migrating away:
+Sometimes you already have old clients using an `application/json` media type identifier when they do requests.
+While this is not a good practise as this makes it hard to add new fields or remove old ones, this library has support for migrating away:
 
 ```ruby
 class BookSerializer < MediaTypes::Serialization::Base
@@ -475,7 +486,8 @@ Validation will be done using the remapped validator. Aliasses map to version `n
 
 ### HTML
 
-This library has a built in API viewer. The viewer can be accessed by by appending a `?api_viewer=last` query parameter to the URL.
+This library has a built in API viewer.
+The viewer can be accessed by by appending a `?api_viewer=last` query parameter to the URL.
 
 To enable the API viewer, use: `allow_api_viewer` in the controller.
 
@@ -493,7 +505,7 @@ class BookController < ActionController::API
     book = Book.new
     book.title = 'Everything, abridged'
 
-    render media: serialize_media(book), content_type: request.format.to_s
+    render_media serialize_media(book)
   end
 
   def create
@@ -531,17 +543,18 @@ end
 
 #### Errors
 
-This library adds support for returning errors to clients using the [`application/problem+json`](https://tools.ietf.org/html/rfc7231) media type. You can catch and transform application errors by adding an `output_error` call before `freeze_io!`:
+This library adds support for returning errors to clients using the [`application/problem+json`](https://tools.ietf.org/html/rfc7231) media type.
+You can catch and transform application errors by adding an `output_error` call before `freeze_io!`:
 
 ```ruby
 class BookController < ActionController::API
   include MediaTypes::Serialization
 
-  output_error CanCan::AccessDenied do |p, error|
-    p.title 'You do not have enough permissions to perform this action.', lang: 'en'
-    p.title 'Je hebt geen toestemming om deze actie uit te voeren.', lang: 'nl-NL'
+  output_error CanCan::AccessDenied do |problem_output, error|
+    problem_output.title 'You do not have enough permissions to perform this action.', lang: 'en'
+    problem_output.title 'Je hebt geen toestemming om deze actie uit te voeren.', lang: 'nl-NL'
 
-    p.status_code :forbidden
+    problem_output.status_code :forbidden
   end
 
   freeze_io!
@@ -550,12 +563,14 @@ class BookController < ActionController::API
 end
 ```
 
-The exception you specified will be rescued by the controller and will be displayed to the user along with a link to the shared wiki page for that error type. Feel free to add instructions there on how clients should solve this problem. You can find more information at: [https://docs.delftsolutions.nl/wiki/Error](https://docs.delftsolutions.nl/wiki/Error)
-If you want to override this url you can use the `p.url(href)` function.
+The exception you specified will be rescued by the controller and will be displayed to the user along with a link to the shared wiki page for that error type. Feel free to add instructions there on how clients should solve this problem.
+You can find more information at: [https://docs.delftsolutions.nl/wiki/Error](https://docs.delftsolutions.nl/wiki/Error)
+If you want to override this url you can use the `problem_output.url(href)` function.
 
-By default the `message` property of the error is used to fill the `details` field. You can override this by using the `p.override_details(description, lang:)` function.
+By default the `message` property of the error is used to fill the `details` field.
+You can override this by using the `problem_output.override_details(description, lang:)` function.
 
-Custom attributes can be added using the `p.attribute(name, value)` function.
+Custom attributes can be added using the `problem_output.attribute(name, value)` function.
 
 ### Related
 
@@ -563,7 +578,7 @@ Custom attributes can be added using the `p.attribute(name, value)` function.
 
 ## API
 
-### Serializer definition
+### Serializer class definition
 
 These methods become available during class definition if you inherit from `MediaTypes::Serialization::Base`.
 
@@ -581,65 +596,95 @@ Either validator or unvalidated must be used while defining a serializer.
 
 #### `output( view:, version:, versions: ) do |obj, version, context|`
 
-Defines a serialization block. Either version or versions can be set. View should be a symbol or unset.
+Defines a serialization block. Either version or versions can be set.
+`nil` is allowed for unversioned.
+View should be a symbol or unset.
 
-Obj is the object to be serialized, version is the negotiated version and context is the context passed in from the serialize function. When using the controller integration, context is the current controller.
+Obj is the object to be serialized, version is the negotiated version and context is the context passed in from the serialize function.
+When using the controller integration, context is the current controller.
 
 The block should return an object to convert into JSON.
 
-#### `output_raw( view:, version:, versions: ) do |obj, version, context|`
+#### `output_raw( view:, version:, versions:, suffix: ) do |obj, version, context|`
 
-This has the same behavior as `output` but should return a string instead of an object. Output is not validated.
+This has the same behavior as `output` but should return a string instead of an object.
+Output is not validated.
+By default, `input_raw` is expected to _not_ be JSON.
+Override `suffix` with `:json` if it _is_ JSON.
 
-#### `output_alias( media_type_identifier, view:, hide_variant: false )`
+#### `output_alias( media_type_identifier, view:, hide_variant: false, suffix: '~' )`
 
-Defines a legacy mapping. This will make the deserializer parse the media type `media_type_identifier` as if it was version `nil` of the specified view. If view is undefined it will use the output serializer without a view defined.
+Defines a legacy mapping. This will make the deserializer parse the media type `media_type_identifier` as if it was version `nil` of the specified view.
+If `view` is undefined it will use the output serializer without a view defined.
+By default, suffix is `:json` if `media_type_identifier` is a JSON type.
 
-Response will have a content type equal to `[media_type_identifier]; variant=[mapped_media_type_identifier]`. If `hide_variant:` is true, the content type emitted will only be `[media_type_identifier]`.
+Response will have a content type equal to `[media_type_identifier]; variant=[mapped_media_type_identifier]`.
+If `hide_variant:` is true, the content type emitted will only be `[media_type_identifier]`.
+
+> You cannot alias a _versioned_ media type, otherwise it would be easy to later break the definition by changing the version it aliases.
 
-#### `output_alias_optional( media_type_identifier, view:, hide_variant: false )`
+#### `output_alias_optional( media_type_identifier, view:, hide_variant: false, suffix: '~' )`
 
-Has the same behavior as `output_alias` but can be used by multiple serializers. The serializer that is loaded last in the controller 'wins' control over this media type identifier. If any of the serializers have an `output_alias` defined with the same media type identifier that one will win instead.
+Has the same behavior as `output_alias` but can be used by multiple serializers.
+The serializer that is loaded last in the controller 'wins' control over this media type identifier.
+If any of the serializers have an `output_alias` defined with the same media type identifier that one will win instead.
+By default, suffix is `:json` if `media_type_identifier` is a JSON type.
 
 Response will have a content type equal to `[media_type_identifier]; variant=[mapped_media_type_identifier]`. If `hide_variant:` is true, the content type emitted will only be `[media_type_identifier]`.
 
 #### `input( view:, version:, versions: ) do |obj, version, context|`
 
-Defines a deserialization block. Either version or versions can be set. View should be a symbol or unset.
+Defines a deserialization block. Either version or versions can be set.
+View should be a symbol or unset.
 
-Obj is the object to be serialized, version is the negotiated version and context is the context passed in from the serialize function. When using the controller integration, context is the current controller.
+Obj is the object to be serialized, version is the negotiated version and context is the context passed in from the serialize function.
+When using the controller integration, context is the current controller.
 
-The block should return the internal representation of the object. Best practise is to make sure not to change state in this function but to leave that up to the controller.
+The block should return the internal representation of the object.
+Best practise is to make sure not to change state in this function but to leave that up to the controller.
 
-#### `input_raw( view:, version:, versions: ) do |bytes, version, context|`
+#### `input_raw( view:, version:, versions:, suffix: nil ) do |bytes, version, context|`
 
-This has the same behavior as `input` but takes in raw data. Input is not validated.
+This has the same behavior as `input` but takes in raw data.
+Input is not validated.
+By default, `input_raw` is expected to _not_ be JSON.
+Override `suffix` with `:json` if it _is_ JSON.
 
-#### `input_alias( media_type_identifier, view: )`
+#### `input_alias( media_type_identifier, view:, suffix: '~' )`
 
-Defines a legacy mapping. This will make the serializer parse the media type `media_type_identifier` as if it was version 1 of the specified view. If view is undefined it will use the input serializer without a view defined.
+Defines a legacy mapping.
+This will make the serializer parse the media type `media_type_identifier` as if it was version `nil` of the specified view.
+If view is undefined it will use the input serializer without a view defined.
+By default, suffix is `:json` if `media_type_identifier` is a JSON type.
 
-#### `input_alias_optional( media_type_identifier, view: )`
+> You cannot alias a _versioned_ media type, otherwise it would be easy to later break the definition by changing the version it aliases.
 
-Has the same behavior as `input_alias` but can be used by multiple serializers. The serializer that is loaded last in the controller 'wins' control over this media type identifier. If any of the serializers have an `input_alias` defined with the same media type identifier that one will win instead.
+#### `input_alias_optional( media_type_identifier, view:, suffix: '~' )`
+
+Has the same behavior as `input_alias` but can be used by multiple serializers.
+The serializer that is loaded last in the controller 'wins' control over this media type identifier.
+If any of the serializers have an `input_alias` defined with the same media type identifier that one will win instead.
+By default, suffix is `:json` if `media_type_identifier` is a JSON type.
 
 #### `disable_wildcards`
 
 Disables registering wildcard media types.
 
-### Serializer definition
+### Serializer output definition
 
 The following methods are available within an `output ... do` block.
 
 #### `attribute( key, value = {} ) do`
 
-Sets a value for the given key. If a block is given, any `attribute`, `link`, `collection` and `index` statements are run in context of `value`.
+Sets a value for the given key.
+If a block is given, any `attribute`, `link`, `collection` and `index` statements are run in context of `value`.
 
 Returns the built up context so far.
 
 #### `link( rel, href:, emit_header: true, **attributes )`
 
-Adds a `_link` block to the current context. Also adds the specified link to the HTTP Link header. `attributes` allows passing in custom attributes.
+Adds a `_link` block to the current context. Also adds the specified link to the HTTP Link header.
+`attributes` allows passing in custom attributes.
 
 If `emit_header` is `true` the link will also be emitted as a http header.
 
@@ -647,12 +692,16 @@ Returns the built up context so far.
 
 #### `index( array, serializer, version:, view: nil )`
 
+> Not the same as a validator `collection`.
+
 Adds an `_index` block to the current context. Uses the self links of the specified view to construct an index of urls to the child objects.
 
 Returns the built up context so far.
 
 #### `collection( array, serializer, version:, view: nil )`
 
+> Not the same as a validator `collection`.
+
 Adds an `_embedded` block to the current context. Uses the specified serializer to embed the child objects.
 Optionally a block can be used to modify the output from the child serializer.
 
@@ -660,7 +709,9 @@ Returns the built up context so far.
 
 #### `hidden do`
 
-Sometimes you want to add links without actually modifying the object. Calls to `attribute`, `link`, `index`, `collection` made inside this block won't modify the context. Any calls to link will only set the HTTP Link header.
+Sometimes you want to add links without actually modifying the object.
+Calls to `attribute`, `link`, `index`, `collection` made inside this block won't modify the context.
+Any calls to link will only set the HTTP Link header.
 
 Returns the unmodified context.
 
@@ -674,9 +725,25 @@ Returns the built up context so far.
 
 Runs a block in a new context and returns the result
 
+> Most common use-case is emitting from an enumerable.
+>
+> ```ruby
+> results = [item, item, item].map do |current_item|
+>   object do
+>     attribute :foo, current_item.bar
+>   end
+> end
+>
+> attribute :items, results
+> ```
+
 #### `render_view( view, context:, **args)`
 
-Can be used to render a view. You can set local variables in the view by assigning a hash to the `assigns:` parameter.
+Can be used to render a view.
+You can set local variables in the view by assigning a hash to the `assigns:` parameter.
+Returns a `string`
+
+> When possible, prefer `output_raw` with `context.class.render(params)`
 
 ### Controller definition
 
@@ -684,7 +751,8 @@ These functions are available during the controller definition if you add `inclu
 
 #### `allow_output_serializer( serializer, views: nil, **filters )`
 
-Configure the controller to allow the client to request responses emitted by the specified serializer. Optionally allows you to specify which views to allow by passing an array in the views parameter.
+Configure the controller to allow the client to request responses emitted by the specified serializer.
+Optionally allows you to specify which views to allow by passing an array in the views parameter.
 
 Accepts the same filters as `before_action`.
 
@@ -692,9 +760,11 @@ Accepts the same filters as `before_action`.
 
 Allows falling back to the default Rails view rendering when the client asks for the media type in the `as:` parameter or `text/html` if `as:` is unset.
 
-The `Content-Type` of the response will be `text/html` if the `as:` parameter is unset. If the `as:` parameter is set, it will include it in the variant parameter: `text/html; variant=application/vnd.xpbytes.borderless`.
+The `Content-Type` of the response will be `text/html` if the `as:` parameter is unset.
+If the `as:` parameter is set, it will include it in the variant parameter: `text/html; variant=application/vnd.xpbytes.borderless`.
 
-Accepts the same filters as `before_action`. You can set the template to use using the `view:` parameter.
+Accepts the same filters as `before_action`.
+You can set the template to use using the `view:` parameter.
 
 #### `allow_output_docs( description, **filters )`
 
@@ -704,7 +774,8 @@ Accepts the same filters as `before_action`.
 
 #### `allow_input_serializer( serializer, views: nil, **filters )`
 
-Configure the controller to allow the client to send bodies with a `Content-Type` that can be deserialized using the specified serializer. Optionally allows you to specify which views to allow by passing an array in the views parameter.
+Configure the controller to allow the client to send bodies with a `Content-Type` that can be deserialized using the specified serializer.
+Optionally allows you to specify which views to allow by passing an array in the views parameter.
 
 Accepts the same filters as `before_action`.
 
@@ -738,7 +809,8 @@ Enables rendering the api viewer when adding the `api_viewer=last` query paramet
 
 #### `freeze_io!(**filter_opts)`
 
-Registers serialization and deserialization in the controller. This function must be called before using the controller.
+Registers serialization and deserialization in the controller.
+This function must be called before using the controller.
 
 ### Controller usage
 
@@ -746,7 +818,8 @@ These functions are available during method execution in the controller.
 
 #### `render_media( obj, serializers: nil, not_acceptable_serializer: nil, **options ) do`
 
-Serializes an object and renders it using the appropriate content type. Options are passed through to the controller `render` function. Allows you to specify different objects to different serializers using a block:
+Serializes an object and renders it using the appropriate content type.
+Options are passed through to the controller `render` function. Allows you to specify different objects to different serializers using a block:
 
 ```ruby
 render_media do
@@ -757,13 +830,15 @@ render_media do
 end
 ```
 
-Warning: this block can be called multiple times when used together with recursive serializers like the API viewer. Try to avoid changing state in this block.
+**Warning**: this block can be called multiple times when used together with recursive serializers like the API viewer.
+Try to _avoid changing state_ in this block.
 
 If you want to render with different serializers than defined in the controller you can pass an array of serializers in the `serializers` property.
 
 If you want to override the serializer that is used to render the response when no acceptable Content-Type could be negotiated you can pass the desired serializer in the `not_acceptable_serializer` property.
 
-This method throws a `MediaTypes::Serialization::OutputValidationFailedError` error if the output does not conform to the format defined by the configured validator. Best practise is to return a 500 error to the client.
+This method throws a `MediaTypes::Serialization::OutputValidationFailedError` error if the output does not conform to the format defined by the configured validator.
+Best practise is to return a 500 error to the client.
 
 If no acceptable Content-Type could be negotiated the response will be rendered using the serialized defined by the class `not_acceptable_serializer` function or by the `not_acceptable_serializer` property.
 
@@ -805,12 +880,11 @@ HERE
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can
-also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
-version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
-push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/lib/media_types/serialization.rb

@@ -184,7 +184,7 @@ module MediaTypes
         end
       end
 
-      def allow_output_html(as: nil, view: nil, layout: nil, **filter_opts)
+      def allow_output_html(as: nil, view: nil, layout: nil, formats: [:html], variants: nil, **filter_opts)
         before_action(**filter_opts) do
           raise SerializersAlreadyFrozenError if defined? @serialization_frozen
 
@@ -197,19 +197,13 @@ module MediaTypes
           validator = FakeValidator.new(as.nil? ? 'text/html' : as)
 
           block = lambda { |_, _, controller|
-            if layout.nil?
-              if view.nil?
-                controller.render_to_string
-              else
-                controller.render_to_string(template: view)
-              end
-            else
-              if view.nil?
-                controller.render_to_string(layout: layout)
-              else
-                controller.render_to_string(template: view, layout: layout)
-              end
-            end
+            options = {}
+            options[:layout] = layout unless layout.nil?
+            options[:template] = view unless view.nil?
+            options[:formats] = formats unless formats.nil?
+            options[:variants] = variants unless variants.nil?
+
+            controller.render_to_string(**options)
           }
 
           html_registration.register_block(nil, validator, nil, block, true, wildcards: true)
@@ -342,11 +336,6 @@ module MediaTypes
     end
     # rubocop:enable Metrics/BlockLength
 
-    included do
-      protected
-
-    end
-
     protected
 
     def serialize(victim, media_type, serializer: Object.new, links: [], vary: ['Accept'])
@@ -356,7 +345,10 @@ module MediaTypes
 
     MEDIA_TYPES_SERIALIZATION_OBJ_IS_UNDEFINED = ::Object.new
 
-    def render_media(obj = MEDIA_TYPES_SERIALIZATION_OBJ_IS_UNDEFINED, serializers: nil, not_acceptable_serializer: nil, **options, &block)
+    def render_media(obj = MEDIA_TYPES_SERIALIZATION_OBJ_IS_UNDEFINED, **options, &block)
+      serializers = options.delete(:serializers)
+      not_acceptable_serializer = options.delete(:not_acceptable_serializer)
+
       if obj == MEDIA_TYPES_SERIALIZATION_OBJ_IS_UNDEFINED && options.keys.any? && !block
         # options is too greedy :(
         obj = options
@@ -366,6 +358,7 @@ module MediaTypes
       if obj == MEDIA_TYPES_SERIALIZATION_OBJ_IS_UNDEFINED && block.nil?
         raise 'render_media was called without an object. Please provide one or supply a block to match the serializer.'
       end
+
       obj = nil if obj == MEDIA_TYPES_SERIALIZATION_OBJ_IS_UNDEFINED
 
       raise SerializersNotFrozenError unless defined? @serialization_frozen
@@ -395,10 +388,17 @@ module MediaTypes
         selector.instance_exec(&block)
 
         raise UnmatchedSerializerError, serializer unless selector.matched
+
         obj = selector.value
       end
 
-      serialization_render_resolved(obj: obj, serializer: serializer, identifier: identifier, registrations: registration, options: options)
+      serialization_render_resolved(
+        obj: obj,
+        serializer: serializer,
+        identifier: identifier,
+        registrations: registration,
+        options: options
+      )
     end
 
     def deserialize(request)
@@ -417,6 +417,7 @@ module MediaTypes
       raise SerializersNotFrozenError unless defined?(@serialization_frozen)
       raise NoInputReceivedError if request.content_type.blank?
       raise InputNotAcceptableError unless @serialization_input_registrations.has? request.content_type
+
       @serialization_input_registrations.call(@serialization_decoded_input, request.content_type, self)
     end
 
@@ -427,6 +428,7 @@ module MediaTypes
       registration = registration.registrations[identifier]
 
       raise 'Assertion failed, inconsistent answer from resolve_media_type' if registration.nil?
+
       registration.serializer
     end
 
@@ -434,8 +436,12 @@ module MediaTypes
 
     def resolve_media_type(request, registration, allow_last: true)
       if defined? @serialization_override_accept
-        @serialization_override_accept = registration.registrations.keys.last if allow_last && @serialization_override_accept == 'last'
+        if allow_last && @serialization_override_accept == 'last'
+          @serialization_override_accept = registration.registrations.keys.last
+        end
+
         return nil unless registration.has? @serialization_override_accept
+
         return @serialization_override_accept
       end
 
@@ -483,7 +489,10 @@ module MediaTypes
       input_is_allowed = @serialization_input_registrations.has? request.content_type unless request.content_type.blank?
 
       unless input_is_allowed || all_allowed
-        serializers = @serialization_unsupported_media_type_serializer || [MediaTypes::Serialization::Serializers::ProblemSerializer, MediaTypes::Serialization::Serializers::FallbackUnsupportedMediaTypeSerializer]
+        serializers = @serialization_unsupported_media_type_serializer || [
+          MediaTypes::Serialization::Serializers::ProblemSerializer,
+          MediaTypes::Serialization::Serializers::FallbackUnsupportedMediaTypeSerializer
+        ]
         registrations = SerializationRegistration.new(:output)
         serializers.each do |s|
           registrations = registrations.merge(s.outputs_for(views: [nil, :html]))
@@ -511,7 +520,10 @@ module MediaTypes
           input_data = request.body.read
           @serialization_decoded_input = @serialization_input_registrations.decode(input_data, request.content_type, self)
         rescue InputValidationFailedError => e
-          serializers = @serialization_input_validation_failed_serializer || [MediaTypes::Serialization::Serializers::ProblemSerializer, MediaTypes::Serialization::Serializers::InputValidationErrorSerializer]
+          serializers = @serialization_input_validation_failed_serializer || [
+            MediaTypes::Serialization::Serializers::ProblemSerializer,
+            MediaTypes::Serialization::Serializers::InputValidationErrorSerializer
+          ]
           registrations = SerializationRegistration.new(:output)
           serializers.each do |s|
             registrations = registrations.merge(s.outputs_for(views: [nil, :html]))
@@ -557,7 +569,13 @@ module MediaTypes
           actions: @serialization_available_serializers,
         }
 
-        serialization_render_resolved obj: input, serializer: description_serializer, identifier: endpoint_matched_identifier, registrations: @serialization_output_registrations, options: {}
+        serialization_render_resolved(
+          obj: input,
+          serializer: description_serializer,
+          identifier: endpoint_matched_identifier,
+          registrations: @serialization_output_registrations,
+          options: {}
+        )
         return
       end
 
@@ -603,7 +621,7 @@ module MediaTypes
           output: result,
           links: links,
         }
-        wrapped = @serialization_wrapping_renderer.serialize input, '*/*', self
+        wrapped = @serialization_wrapping_renderer.serialize input, '*/*', context: self
         render body: wrapped
 
         response.content_type = 'text/html'

data/lib/media_types/serialization/base.rb

@@ -44,35 +44,76 @@ module MediaTypes
             validator = serializer_validator.view(view).version(v)
             validator.override_suffix(:json) unless serializer_validated
 
-            serializer_output_registration.register_block(self, validator, v, block, false, wildcards: !self.serializer_disable_wildcards)
+            serializer_output_registration.register_block(
+              self,
+              validator,
+              v,
+              block,
+              false,
+              wildcards:
+              !serializer_disable_wildcards
+            )
           end
         end
 
-        def output_raw(view: nil, version: nil, versions: nil, &block)
+        def output_raw(view: nil, version: nil, versions: nil, suffix: nil, &block)
           versions = [version] if versions.nil?
           raise VersionsNotAnArrayError unless versions.is_a? Array
 
           raise ValidatorNotSpecifiedError, :output if serializer_validator.nil?
 
           versions.each do |v|
-            validator = serializer_validator.view(view).version(v)
-
-            serializer_output_registration.register_block(self, validator, v, block, true, wildcards: !self.serializer_disable_wildcards)
+            validator = serializer_validator.view(view)
+                                            .version(v)
+                                            .override_suffix(suffix)
+
+            serializer_output_registration.register_block(
+              self,
+              validator,
+              v,
+              block,
+              true,
+              wildcards: !serializer_disable_wildcards
+            )
           end
         end
 
-        def output_alias(media_type_identifier, view: nil, hide_variant: false)
-          validator = serializer_validator.view(view)
+        def output_alias(
+          media_type_identifier,
+          view: nil,
+          suffix: media_type_identifier == 'application/json' || media_type_identifier.end_with?('+json') ? :json : nil,
+          hide_variant: false
+        )
+          validator = serializer_validator.view(view).override_suffix(suffix)
           victim_identifier = validator.identifier
 
-          serializer_output_registration.register_alias(self, media_type_identifier, victim_identifier, false, hide_variant, wildcards: !self.serializer_disable_wildcards)
-        end
-
-        def output_alias_optional(media_type_identifier, view: nil, hide_variant: false)
-          validator = serializer_validator.view(view)
+          serializer_output_registration.register_alias(
+            self,
+            media_type_identifier,
+            victim_identifier,
+            false,
+            hide_variant,
+            wildcards: !serializer_disable_wildcards
+          )
+        end
+
+        def output_alias_optional(
+          media_type_identifier,
+          view: nil,
+          suffix: media_type_identifier == 'application/json' || media_type_identifier.end_with?('+json') ? :json : nil,
+          hide_variant: false
+        )
+          validator = serializer_validator.view(view).override_suffix(suffix)
           victim_identifier = validator.identifier
 
-          serializer_output_registration.register_alias(self, media_type_identifier, victim_identifier, true, hide_variant, wildcards: !self.serializer_disable_wildcards)
+          serializer_output_registration.register_alias(
+            self,
+            media_type_identifier,
+            victim_identifier,
+            true,
+            hide_variant,
+            wildcards: !serializer_disable_wildcards
+          )
         end
 
         def input(view: nil, version: nil, versions: nil, &block)
@@ -89,39 +130,61 @@ module MediaTypes
           end
         end
 
-        def input_raw(view: nil, version: nil, versions: nil, &block)
+        def input_raw(view: nil, version: nil, versions: nil, suffix: nil, &block)
           versions = [version] if versions.nil?
           raise VersionsNotAnArrayError unless versions.is_a? Array
 
           raise ValidatorNotSpecifiedError, :input if serializer_validator.nil?
 
           versions.each do |v|
-            validator = serializer_validator.view(view).version(v)
+            validator = serializer_validator.view(view).version(v).override_suffix(suffix)
 
             serializer_input_registration.register_block(self, validator, v, block, true)
           end
         end
 
-        def input_alias(media_type_identifier, view: nil)
-          validator = serializer_validator.view(view)
+        def input_alias(
+          media_type_identifier,
+          view: nil,
+          suffix: media_type_identifier == 'application/json' || media_type_identifier.end_with?('+json') ? :json : nil
+        )
+          validator = serializer_validator.view(view).override_suffix(suffix)
           victim_identifier = validator.identifier
 
-          serializer_input_registration.register_alias(self, media_type_identifier, victim_identifier, false)
-        end
-
-        def input_alias_optional(media_type_identifier, view: nil)
-          validator = serializer_validator.view(view)
+          serializer_input_registration.register_alias(
+            self,
+            media_type_identifier,
+            victim_identifier,
+            false,
+            true,
+            wildcards: false
+          )
+        end
+
+        def input_alias_optional(
+          media_type_identifier,
+          view: nil,
+          suffix: media_type_identifier == 'application/json' || media_type_identifier.end_with?('+json') ? :json : nil
+        )
+          validator = serializer_validator.view(view).override_suffix(suffix)
           victim_identifier = validator.identifier
 
-          serializer_input_registration.register_alias(self, media_type_identifier, victim_identifier, true)
+          serializer_input_registration.register_alias(
+            self,
+            media_type_identifier,
+            victim_identifier,
+            true,
+            true,
+            wildcards: false
+          )
         end
 
-        def serialize(victim, media_type_identifier, context, dsl: nil, raw: nil)
+        def serialize(victim, media_type_identifier, context:, dsl: nil, raw: nil)
           dsl ||= SerializationDSL.new(self, context: context)
           serializer_output_registration.call(victim, media_type_identifier.to_s, context, dsl: dsl, raw: raw)
         end
 
-        def deserialize(victim, media_type_identifier, context)
+        def deserialize(victim, media_type_identifier, context:)
           serializer_input_registration.call(victim, media_type_identifier, context)
         end
 
@@ -135,6 +198,8 @@ module MediaTypes
       end
 
       def self.inherited(subclass)
+        super
+
         subclass.extend(ClassMethods)
         subclass.instance_eval do
           class << self

data/lib/media_types/serialization/fake_validator.rb

@@ -22,6 +22,7 @@ class FakeValidator
 
   def override_suffix(suffix)
     suffixes[[internal_view, internal_version]] = suffix
+    FakeValidator.new(prefix, internal_view, version, suffixes)
   end
 
   def identifier

data/lib/media_types/serialization/serialization_dsl.rb

@@ -56,7 +56,7 @@ module MediaTypes
         array.each do |e|
           child_links = []
           context = SerializationDSL.new(__getobj__, child_links, context: @serialization_context)
-          serializer.serialize(e, identifier, @serialization_context, dsl: context)
+          serializer.serialize(e, identifier, context: @serialization_context, dsl: context)
 
           self_links = child_links.select { |l| l[:rel] == :self }
           raise NoSelfLinkProvidedError, identifier unless self_links.any?
@@ -79,7 +79,7 @@ module MediaTypes
 
         array.each do |e|
           context = SerializationDSL.new(__getobj__, [], @serialization_vary, context: @serialization_context)
-          result = serializer.serialize(e, identifier, @serialization_context, dsl: context, raw: true)
+          result = serializer.serialize(e, identifier, context: @serialization_context, dsl: context, raw: true)
 
           result = block.call(result) unless block.nil?
 
@@ -105,7 +105,7 @@ module MediaTypes
       def emit
         serialization_dsl_result
       end
-      
+
       def object(&block)
         context = SerializationDSL.new(__getobj__, @serialization_links, @serialization_vary, context: @serialization_context)
         context.instance_exec(&block)

data/lib/media_types/serialization/serialization_registration.rb

@@ -36,7 +36,7 @@ module MediaTypes
 
         unless registrations.key? target_identifier
           potential_match = registrations.keys.find do |k|
-            k.starts_with? target_identifier
+            k.start_with? target_identifier
           end
           raise VersionedAliasDefinitionError.new(target_identifier, inout, potential_match) unless potential_match.nil?
           raise UnbackedAliasDefinitionError.new(target_identifier, inout)
@@ -152,7 +152,7 @@ module MediaTypes
         self.raw = raw
         super(serializer, inout, validator, display_identifier)
       end
-      
+
       def merge(other)
         return nil unless other.is_a?(SerializationAliasRegistration)
 

data/lib/media_types/serialization/version.rb

@@ -1,5 +1,5 @@
 module MediaTypes
   module Serialization
-    VERSION = '1.2.0'.freeze
+    VERSION = '1.3.4'.freeze
   end
 end

data/media_types-serialization.gemspec

@@ -37,7 +37,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'actionpack', '>= 4.0.0'
   spec.add_dependency 'activesupport', '>= 4.0.0'
-  spec.add_dependency 'media_types', '>= 2.0.0', '< 3.0.0'
+  spec.add_dependency 'media_types', '>= 2.1.0', '< 3.0.0'
 
   spec.add_development_dependency 'awesome_print'
   spec.add_development_dependency 'bundler'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: media_types-serialization
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.4
 platform: ruby
 authors:
 - Derk-Jan Karrenbeld
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-13 00:00:00.000000000 Z
+date: 2021-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -45,7 +45,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 2.1.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 3.0.0
@@ -55,7 +55,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 2.1.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 3.0.0