media_types-serialization 1.0.3 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f06cbbb5eb9ccdb11dfa751a8fa3d20b03e675a3b94f6393538acda79f61081d
-  data.tar.gz: 4b8347532cfdc1e9020189ad1a50a047bf8699df0705f602bdbb2340a5a44f8e
+  metadata.gz: a7e886054d63df27dd6a7cd6deca3d00d9b0a58edcb4a3fa30ae45f369dc2c20
+  data.tar.gz: c601dca445a03064381dc387a3db4395e97bd8ef427710a591318df699380aa8
 SHA512:
-  metadata.gz: a6d56c098681e1a854b9284a08fa18b56542b1786fec6dbe58182af59da487d21526bd2cdcd7ddb08ee03277201f4e710ce9e1a0b57c09bbfa196d38d12e1227
-  data.tar.gz: 45eeb2cb62c4c100e13513eba6a1ef97ce0953ed22b21d70cef3f1f142f52d183b9d596906e76d8f29e110b85030077273b0eee6b9a15e494c05343cdc2d0d25
+  metadata.gz: 5b23ee08585bbe29ca4caff191afd280745f5325082e9ba4b9f2f0a797ba0fc8368e2df8b21fcb8aa32d50d10740461503bdcfc1c669a5fc5615dac4f6508500
+  data.tar.gz: 8ae9a64b67d90619947fcf4d50629f2885786776996c070398b12a7b4753caebbb3523a7bce96d91b82a2f1f2c261b2c77490ada853f9b28e4bc49ef7596f2ed

data/.github/workflows/ci.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - master
   push:
-    branches: 
+    branches:
       - master
       - depfu/*
       - release/*
@@ -16,12 +16,16 @@ jobs:
 
     runs-on: ubuntu-latest
 
+    strategy:
+      matrix:
+        ruby-version: [2.7.x, 2.6.x]
+
     steps:
     - uses: actions/checkout@v1
-    - name: Set up Ruby 2.6
+    - name: Set up Ruby ${{ matrix.ruby-version }}
       uses: actions/setup-ruby@v1
       with:
-        ruby-version: 2.6.x
+        ruby-version: ${{ matrix.ruby-version }}
     - name: Build and test with Rake
       run: |
         gem install bundler

data/.prettierrc

@@ -0,0 +1 @@
+{}

data/CHANGELOG.md

@@ -1,27 +1,54 @@
 # Changelog
 
+## 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.
+
+## 1.1.0
+
+- ✨ Add _allow_output_html_: Fallback to rails rendering.
+- ✨ Add _allow_output_docs_: Useful to add a documentation description to endpoints that you can normally only POST to.
+- ✨ Add _output_error_: Implements missing content-language support.
+- ✨ Add _scoped freeze_io! support_: Useful for gradual adoption of mediatypes on existing routes.
+- ✨ Add _alias variant reporting_: Allows reporting what the original matched media type was even when impersonating a different media type.
+- ✨ Improve README: small improvements to make it easier to adopt and upgrade existing codebase.
+- ✨ Reduce number of (external) dependencies
+- 🐛 Fix incorrect output on encoding errors.
+- 🐛 Fix message in various alias error messages.
+
 ## 1.0.3
 
- - 🐛 Unvalidated serializers would put the view part of the identifier before the version. This was not in line with validated serializers.
+- 🐛 Unvalidated serializers would put the view part of the identifier before the version. This was not in line with validated serializers.
 
 ## 1.0.2
 
- - 🐛 Explicitly set all oj parameters when decoding as well.
+- 🐛 Explicitly set all oj parameters when decoding as well.
 
 ## 1.0.1
 
- - 🐛 Explicitly set all oj and json parameters to ensure correct behavior with changed defaults.
- - 🐛 Fix serializer not deserializing as symbols.
+- 🐛 Explicitly set all oj and json parameters to ensure correct behavior with changed defaults.
+- 🐛 Fix serializer not deserializing as symbols.
 
 ## 1.0.0
 
 - ✨ Add support for input deserialization.
-- ✨ Added serializer DSL to be more in line with validation gem.
-- ✨ Added ability to make a serializer without a validator.
-- ✨ Added error serializer that emits [`application/problem+json`](https://tools.ietf.org/html/rfc7231).
-- ✨ Reduced number of dependencies.
+- ✨ Add serializer DSL to be more in line with validation gem.
+- ✨ Add ability to make a serializer without a validator.
+- ✨ Add error serializer that emits [`application/problem+json`](https://tools.ietf.org/html/rfc7231).
+- ✨ Reduce number of dependencies.
 - ✨ Validators no longer need to be registered to be used.
-- ✨ Added a [wiki where errors can be documented](https://docs.delftsolutions.nl). Feel free to make pages for your own namespaced errors.
+- ✨ Add a [wiki where errors can be documented](https://docs.delftsolutions.nl). Feel free to make pages for your own namespaced errors.
 - 💔 Serializer definition API has backwards incompatible changes.
 - 💔 API viewer is now no longer registered as html but accessible with the `?api_viewer=last` query parameter.
 - 💔 Validators can no longer be registered for use in `format do`.

data/CODE_OF_CONDUCT.md

@@ -14,21 +14,21 @@ orientation.
 Examples of behavior that contributes to creating a positive environment
 include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or
-advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
   address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Our Responsibilities

data/Gemfile.lock

@@ -1,143 +1,137 @@
-PATH
-  remote: .
-  specs:
-    media_types-serialization (1.0.3)
-      actionpack (>= 4.0.0)
-      activesupport (>= 4.0.0)
-      http_headers-accept (>= 0.2.2, < 1.0.0)
-      http_headers-link (< 1.0.0)
-      media_types (>= 2.0.0, < 3.0.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    actioncable (5.2.4.2)
-      actionpack (= 5.2.4.2)
-      nio4r (~> 2.0)
-      websocket-driver (>= 0.6.1)
-    actionmailer (5.2.4.2)
-      actionpack (= 5.2.4.2)
-      actionview (= 5.2.4.2)
-      activejob (= 5.2.4.2)
-      mail (~> 2.5, >= 2.5.4)
-      rails-dom-testing (~> 2.0)
-    actionpack (5.2.4.2)
-      actionview (= 5.2.4.2)
-      activesupport (= 5.2.4.2)
-      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.4.2)
-      activesupport (= 5.2.4.2)
-      builder (~> 3.1)
-      erubi (~> 1.4)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.3)
-    activejob (5.2.4.2)
-      activesupport (= 5.2.4.2)
-      globalid (>= 0.3.6)
-    activemodel (5.2.4.2)
-      activesupport (= 5.2.4.2)
-    activerecord (5.2.4.2)
-      activemodel (= 5.2.4.2)
-      activesupport (= 5.2.4.2)
-      arel (>= 9.0)
-    activestorage (5.2.4.2)
-      actionpack (= 5.2.4.2)
-      activerecord (= 5.2.4.2)
-      marcel (~> 0.3.1)
-    activesupport (5.2.4.2)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-    arel (9.0.0)
-    awesome_print (1.8.0)
-    builder (3.2.4)
-    concurrent-ruby (1.1.6)
-    crass (1.0.6)
-    erubi (1.9.0)
-    globalid (0.4.2)
-      activesupport (>= 4.2.0)
-    http_headers-accept (0.2.2)
-      http_headers-utils (>= 0.2.0, < 1.0.0)
-    http_headers-link (0.2.1)
-      http_headers-utils (>= 0.2.0, < 1.0.0)
-    http_headers-utils (0.2.0)
-    i18n (1.8.2)
-      concurrent-ruby (~> 1.0)
-    loofah (2.5.0)
-      crass (~> 1.0.2)
-      nokogiri (>= 1.5.9)
-    mail (2.7.1)
-      mini_mime (>= 0.1.1)
-    marcel (0.3.3)
-      mimemagic (~> 0.3.2)
-    media_types (2.0.1)
-    method_source (1.0.0)
-    mimemagic (0.3.4)
-    mini_mime (1.0.2)
-    mini_portile2 (2.4.0)
-    minitest (5.14.0)
-    nio4r (2.5.2)
-    nokogiri (1.10.9)
-      mini_portile2 (~> 2.4.0)
-    oj (3.10.6)
-    rack (2.2.2)
-    rack-test (1.1.0)
-      rack (>= 1.0, < 3)
-    rails (5.2.4.2)
-      actioncable (= 5.2.4.2)
-      actionmailer (= 5.2.4.2)
-      actionpack (= 5.2.4.2)
-      actionview (= 5.2.4.2)
-      activejob (= 5.2.4.2)
-      activemodel (= 5.2.4.2)
-      activerecord (= 5.2.4.2)
-      activestorage (= 5.2.4.2)
-      activesupport (= 5.2.4.2)
-      bundler (>= 1.3.0)
-      railties (= 5.2.4.2)
-      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.4.2)
-      actionpack (= 5.2.4.2)
-      activesupport (= 5.2.4.2)
-      method_source
-      rake (>= 0.8.7)
-      thor (>= 0.19.0, < 2.0)
-    rake (13.0.1)
-    sprockets (4.0.0)
-      concurrent-ruby (~> 1.0)
-      rack (> 1, < 3)
-    sprockets-rails (3.2.1)
-      actionpack (>= 4.0)
-      activesupport (>= 4.0)
-      sprockets (>= 3.0.0)
-    thor (1.0.1)
-    thread_safe (0.3.6)
-    tzinfo (1.2.7)
-      thread_safe (~> 0.1)
-    websocket-driver (0.7.1)
-      websocket-extensions (>= 0.1.0)
-    websocket-extensions (0.1.4)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  awesome_print
-  bundler
-  media_types-serialization!
-  minitest (~> 5.0)
-  oj
-  rails (~> 5.2)
-  rake (~> 13.0)
-
-BUNDLED WITH
-   1.17.3
+PATH
+  remote: .
+  specs:
+    media_types-serialization (1.3.1)
+      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.3)
+    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

@@ -4,7 +4,7 @@
 [![Gem Version](https://badge.fury.io/rb/media_types-serialization.svg)](https://badge.fury.io/rb/media_types-serialization)
 [![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)
 
-`respond_to` on steroids. Add versioned serialization and deserialization to your Rails projects.
+`respond_to` on steroids. Add [HATEOAS](https://docs.delftsolutions.nl/wiki/HATEOAS_API) compatible serialization and deserialization to your Rails projects.
 
 ## Installation
 
@@ -57,9 +57,67 @@ BookSerializer.serialize(book, 'vnd.acme.book.v1+json', context: nil)
 # => { "book": { "title": "Everything, abridged" } }
 ```
 
+### Controller integration
+
+You can integrate the serialization system in rails, giving you automatic [Content-Type negotiation](https://en.wikipedia.org/wiki/Content_negotiation) using the `Accept` header:
+
+```ruby
+require 'media_types/serialization'
+
+class BookController < ActionController::API
+  include MediaTypes::Serialization
+
+  allow_output_serializer(BookSerializer, only: %i[show])
+  freeze_io!
+
+  def show
+    book = Book.new
+    book.title = 'Everything, abridged'
+
+    render_media book
+  end
+end
+```
+
+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:
+
+```ruby
+class BookController < ApplicationController
+  def show
+    @book = Book.new
+
+    # Use view corresponding to the controller
+  end
+end
+```
+
+You can add a json representation as follows:
+
+```ruby
+class BookController < ApplicationController
+  allow_output_serializer(BookSerializer, only: %i[show])
+  allow_output_html
+  freeze_io!
+
+  def show
+    @book = Book.new
+
+    render_media @book
+  end
+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'
@@ -98,30 +156,6 @@ end
 
 For more information, see the [Media Types docs](https://github.com/SleeplessByte/media-types-ruby).
 
-### Controller integration
-
-You can integrate the serialization system in rails, giving you automatic [Content-Type negotiation](https://en.wikipedia.org/wiki/Content_negotiation) using the `Accept` header:
-
-```ruby
-require 'media_types/serialization'
-
-class BookController < ActionController::API
-  include MediaTypes::Serialization
-
-  allow_output_serializer(BookSerializer, only: %i[show])
-  freeze_io!
-      
-  def show 
-    book = Book.new
-    book.title = 'Everything, abridged'
-
-    render_media book
-  end
-end
-```
-
-While using the controller integration the context will always be set to the current controller. This allows you to construct urls.
-
 ### Versioning
 
 To help with supporting older versions, serializers have a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) to construct json objects:
@@ -149,7 +183,8 @@ BookSerializer.serialize(book, BookValidator.version(2), context: nil)
 
 ### Links
 
-When making [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) 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
@@ -188,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
@@ -206,7 +242,7 @@ class BookSerializer < MediaTypes::Serialization::Base
   output view: :index, version: 3 do |arr, version, context|
     attribute :books do
       link :self, href: context.book_index_url
-      
+
       index arr, version: version
     end
   end
@@ -230,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
@@ -248,15 +285,15 @@ class BookSerializer < MediaTypes::Serialization::Base
   output view: :index, version: 3 do |arr, version, context|
     attribute :books do
       link :self, href: context.book_index_url
-      
+
       index arr, version: version
     end
   end
-  
+
   output view: :collection, version: 3 do |arr, version, context|
     attribute :books do
       link :self, href: context.book_collection_url
-      
+
       collection arr, version: version
     end
   end
@@ -299,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
@@ -309,16 +347,16 @@ class BookController < ActionController::API
   allow_output_serializer(BookSerializer, only: %i[show])
   allow_input_serializer(BookSerializer, only: %i[create])
   freeze_io!
-      
-  def show 
+
+  def show
     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
-    json = deserialize(request, context: self) # does validation for us
+    json = deserialize(request) # does validation for us
     puts json
   end
 end
@@ -355,19 +393,19 @@ class BookController < ActionController::API
   allow_output_serializer(BookSerializer, only: %i[show])
   allow_input_serializer(BookSerializer, only: %i[create])
   freeze_io!
-      
-  def show 
+
+  def show
     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, context: self)
+    book = deserialize(request)
     book.save!
 
-    render media: serialize_media(book), content_type request.format.to_s
+    render_media serialize_media(book)
   end
 end
 ```
@@ -376,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
@@ -385,7 +425,7 @@ class BookSerializer < MediaTypes::Serialization::Base
   output_raw view: :raw, version: 3 do |obj, version, context|
     hidden do
       # Make sure links are only set in the headers, not in the body.
-      
+
       link :self, href: context.book_url(obj)
     end
 
@@ -413,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
@@ -445,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.
 
@@ -454,22 +496,20 @@ class BookController < ActionController::API
   include MediaTypes::Serialization
 
   allow_api_viewer
-  
-  allow_output_serializer(MediaTypes::ApiViewer)
 
   allow_output_serializer(BookSerializer, only: %i[show])
   allow_input_serializer(BookSerializer, only: %i[create])
   freeze_io!
-      
-  def show 
+
+  def show
     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
-    json = deserialize(request, context: self) # does validation for us
+    json = deserialize(request) # does validation for us
     puts json
   end
 end
@@ -489,45 +529,48 @@ class BookSerializer < MediaTypes::Serialization::Base
       attribute :description, obj.description if version >= 2
     end
   end
-  
+
   output_raw view: :html do |obj, context|
     render_view 'book/show', context: context, assigns: {
       title: obj.title,
       description: obj.description
     }
   end
-  
+
   output_alias 'text/html', view: :html
 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!
 
-  # ...   
+  # ...
 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: http://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
 
@@ -553,31 +596,47 @@ 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.
+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|`
 
-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.
+
+#### `output_alias( media_type_identifier, view:, hide_variant: false )`
+
+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.
 
-#### `output_alias( media_type_identifier, view: )`
+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]`.
 
-Defines a legacy mapping. This will make the deserializer 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 output serializer without a view defined.
+> 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: )`
+#### `output_alias_optional( media_type_identifier, view:, hide_variant: false )`
 
-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.
+
+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|`
 
@@ -585,11 +644,17 @@ This has the same behavior as `input` but takes in raw data. Input is not valida
 
 #### `input_alias( media_type_identifier, view: )`
 
-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.
+
+> You cannot alias a _versioned_ media type, otherwise it would be easy to later break the definition by changing the version it aliases.
 
 #### `input_alias_optional( media_type_identifier, view: )`
 
-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.
+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.
 
 #### `disable_wildcards`
 
@@ -601,13 +666,15 @@ 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.
 
@@ -628,7 +695,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.
 
@@ -652,13 +721,31 @@ 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`.
+
+#### `allow_output_html( as: nil, view: nil, layout: nil, **filters )`
+
+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`.
+
+Accepts the same filters as `before_action`.
+You can set the template to use using the `view:` parameter.
+
+#### `allow_output_docs( description, **filters )`
+
+Outputs the specified description as help information.
 
 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`.
 
@@ -690,9 +777,10 @@ Clears the list of serializers used to render the error when the client supplies
 
 Enables rendering the api viewer when adding the `api_viewer=last` query parameter to the url.
 
-#### `freeze_io!`
+#### `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
 
@@ -700,7 +788,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
@@ -711,13 +800,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.
 
@@ -740,6 +831,7 @@ Does the same as `deserialize( request )` but gives the client an error page if
 Returns the serializer class that will handle the given request.
 
 ## Customization
+
 The easiest way to customize the look and feel of the built in pages is to provide your own logo and background in an initializer:
 
 ```ruby
@@ -758,12 +850,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