media_types-serialization 0.8.0 → 1.1.0

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)
 
-Add media types supported serialization using your favourite serializer
+`respond_to` on steroids. Add [HATEOAS](https://docs.delftsolutions.nl/wiki/HATEOAS_API) compatible serialization and deserialization to your Rails projects.
 
 ## Installation
 
@@ -21,275 +21,787 @@ And then execute:
 Or install it yourself as:
 
     $ gem install media_types-serialization
-    
-If you have not done this before, and you're using `rails`, install the necessary parts using:
 
-```bash
-rails g media_types:serialization:api_viewer
+## Usage
+
+Serializers help you in converting a ruby object to a representation matching a specified [Media Type validator](https://github.com/SleeplessByte/media-types-ruby) and the other way around.
+
+### Creating a serializer
+
+```ruby
+class BookSerializer < MediaTypes::Serialization::Base
+  unvalidated 'application/vnd.acme.book'
+
+  # outputs with a Content-Type of application/vnd.acme.book.v1+json
+  output version: 1 do |obj, version, context|
+    {
+      book: {
+        title: obj.title
+      }
+    }
+  end
+end
 ```
 
-This will:
+To convert a ruby object to a json representation:
 
-- Add the default `html_wrapper` layout which is an API Viewer used as fallback or the `.api_viewer` format
-- Add the default `template_controller` which allows the API Viewer to post templated links
-- Add the `route` for these templated link forms
-- Add an initializer that registers the `media` renderer and `api_viewer` media type
+```ruby
+class Book
+  attr_accessor :title
+end
 
-## Usage
+book = Book.new
+book.title = 'Everything, abridged'
+
+BookSerializer.serialize(book, 'vnd.acme.book.v1+json', context: nil)
+# => { "book": { "title": "Everything, abridged" } }
+```
 
-In order to use media type serialization you only need to do 2 things:
+### Controller integration
 
-### Serializer
+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:
 
-Add a serializer that can serialize a certain media type. The `to_hash` function will be called _explicitly_ in your
-controller, so you can always use your own, favourite serializer here to do the hefty work. This gem does provide some
-easy tools, usually enough to do most serialization.
-  
 ```ruby
-class Book < ApplicationRecord
-  class Serializer < MediaTypes::Serialization::Base
-    serializes_media_type MyNamespace::MediaTypes::Book
-    
-    def fields
-      if current_media_type.create?
-        return %i[name author]
-      end
-    
-     %i[name author updated_at views]
-    end
+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
 
-    def to_hash
-      extract(serializable, fields).tap do |result|
-        result[:_links] = extract_links unless current_media_type.create?
+    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):
+
+```ruby
+require 'media_types'
+
+class BookValidator
+  include MediaTypes::Dsl
+
+  def self.organisation
+    'acme'
+  end
+
+  use_name 'book'
+
+  validations do
+    version 1 do
+      attribute :book do
+        attribute :title, String
       end
     end
+  end
+end
 
-    alias to_h to_hash
-    
-    protected
-    
-    def extract_self
-      # A serializer gets the controller as context
-      { href: context.api_book_url(serializable) }
-    end
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
 
-    def extract_links
-      { 
-        'self': extract_self,
-        'signatures': { href: context.api_book_signatures_url(serializable) }
+  # outputs with a Content-Type of application/vnd.acme.book.v1+json
+  output version: 1 do |obj, version, context|
+    {
+      book: {
+        title: obj.title
       }
+    }
+  end
+end
+```
+
+For more information, see the [Media Types docs](https://github.com/SleeplessByte/media-types-ruby).
+
+### Versioning
+
+To help with supporting older versions, serializers have a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) to construct json objects:
+
+```ruby
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
+
+  output versions: [1, 2] do |obj, version, context|
+    attribute :book do
+      attribute :title, obj.title
+      attribute :description, obj.description if version >= 2
     end
   end
 end
 ```
-By default, The passed in `MediaType` gets converted into a constructable (via `to_constructable`) and invoked with the
-current `view` (e.g. `create`, `index`, `collection` or ` `). This means that by default it will be able to serialize 
-the latest version you `MediaType` is reporting. The best way to supply your media type is via the [`media_types`](https://github.com/SleeplessByte/media-types-ruby) gem.
 
-#### Multiple suffixes, one serializer
+```ruby
+BookSerializer.serialize(book, BookValidator.version(1), context: nil)
+# => { "book": { "title": "Everything, abridged" } }
+
+BookSerializer.serialize(book, BookValidator.version(2), context: nil)
+# => { "book": { "title": "Everything, abridged", "description": "Mu" } }
+```
+
+### Links
 
-By default, the media renderer will automatically detect and inject the following:
-- suffix `+json` if you define `to_json`
-- suffix `+xml` if you define `to_xml`
-- type `text/html` if you define `to_html`
+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:
 
-If you do _not_ define these methods, only the `default` suffix / type will be used, `accepts_html` for the `text/html` 
-content-type.
+```ruby
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
 
-If you don't define `to_html`, but try to make a serializer output `html`, it will be rendered in the layout at: 
-`serializers/wrapper/html_wrapper.html.erb` (or any other templating extension).
+  output versions: [1, 2, 3] do |obj, version, context|
+    attribute :book do
+      link :self, href: context.book_url(obj) if version >= 3
 
-#### Migrations (versions)
+      attribute :title, obj.title
+      attribute :description, obj.description if version >= 2
+    end
+  end
+end
+```
 
-If the serializer can serialize multiple _versions_, you can supply them through `additional_versions: [2, 3]`. A way to
-handle this is via backward migrations, meaning you'll migrate from the current version back to an older version.
+This returns the following response:
 
 ```ruby
-class Book < ApplicationRecord
-  class BasicSerializer < MediaTypes::Serialization::Base
-  
-    # Maybe it's currently at version 2, so tell the base that this also serializes version 1
-    # You can also use a range to_a: (1...4).to_a
-    # 
-    serializes_media_type MyNamespace::MediaTypes::Book, additional_versions: [1]
-    
-    def to_hash
-      # This enables migrations right when it's being serialized
-      # 
-      migrate do
-        extract(serializable, fields).tap do |result|
-          result[:_links] = extract_links unless current_media_type.create?
-        end
-      end
+BookSerializer.serialize(book, BookValidator.version(3), context: controller)
+# header = Link: <https://example.org/>; rel="self"
+# => {
+#      "book": {
+#        "_links": {
+#          "self": { "href": "https://example.org" }
+#        },
+#        "title": "Everything, abridged",
+#        "description": "Mu"
+#      }
+#    }
+```
+
+### Collections
+
+There are convenience methods for serializing arrays of objects based on a template.
+
+#### 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.
+
+```ruby
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
+
+  output versions: [1, 2, 3] do |obj, version, context|
+    attribute :book do
+      link :self, href: context.book_url(obj) if version >= 3
+
+      attribute :title, obj.title
+      attribute :description, obj.description if version >= 2
     end
-  
-    # This defines migrations. You can use classes, commands or anything else to execute this code
-    # but inline migrations work fine if you don't have a lot of them. 
-    backward_migrations do
-    
-      # This is called if the version requested is 1 _or_ lower. This means you can compose your migrations. The 
-      # migrations with a _lower_ version than the requested version are NOT executed.
-      version 1 do |result|
-        result.tap do |r|
-          if r.key?(:views)
-            r[:views_count] = r.delete(:views)
-          end
-        end
-      end
+  end
+
+  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
 end
 ```
 
-### Controller
+```ruby
+BookSerializer.serialize([book], BookValidator.view(:index).version(3), context: controller)
+# header = Link: <https://example.org/index>; rel="self"
+# => {
+#      "books": {
+#        "_links": {
+#          "self": { "href": "https://example.org" }
+#        },
+#        "_index": [
+#          { "href": "https://example.org" }
+#        ]
+#      }
+#    }
+```
+
+#### Collections
 
-In your base controller, or wherever you'd like, include the `MediaTypes::Serialization` concern. In the controller that
-uses the serialization, you need to explicitly `accept` it if you want to use the built-in lookups.
+A collection inlines the member objects. The collection method automatically generates it based on the default view of the same version.
 
 ```ruby
-require 'media_types/serialization'
-require 'media_types/serialization/renderer/register'
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
 
-class ApiController < ActionController::API
-  include MediaTypes::Serialization
+  output versions: [1, 2, 3] do |obj, version, context|
+    attribute :book do
+      link :self, href: context.book_url(obj) if version >= 3
+
+      attribute :title, obj.title
+      attribute :description, obj.description if version >= 2
+    end
+  end
+
+  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
+end
+```
+
+```ruby
+BookSerializer.serialize([book], BookValidator.view(:collection).version(3), context: controller)
+# header = Link: <https://example.org/collection>; rel="self"
+# => {
+#      "books": {
+#        "_links": {
+#          "self": { "href": "https://example.org" }
+#        },
+#        "_embedded": [
+#          {
+#            "_links": {
+#              "self": { "href": "https://example.org" }
+#            },
+#            "title": "Everything, abridged",
+#            "description": "Mu"
+#          }
+#        ]
+#      }
+#    }
+```
+
+### Input deserialization
+
+You can mark a media type as something that's allowed to be sent along with a PUT request as follows:
+
+```ruby
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
+
+  output versions: [1, 2, 3] do |obj, version, context|
+    attribute :book do
+      link :self, href: context.book_url(obj) if version >= 3
+
+      attribute :title, obj.title
+      attribute :description, obj.description if version >= 2
+    end
+
+  input version: 3
 end
 
-class BookController < ApiController
-
-  accept_serialization(Book::BasicSerializer, accept_html: false, only: %i[show])
-  accept_html(Book::CoverHtmlSerializer, only: %i[show])
-  freeze_accepted_media!
-      
-  def show 
-    # If you do NOT pass in the content_type, it will re-use the current content_type of the response if set or
-    # use the default content type of the serializer. This is fine if you only output one Content-Type in the
-    # action, but not if you are relying on content-negotiation. 
-    
-    render media: serialize_media(@book), content_type: request.format.to_s
+class BookController < ActionController::API
+  include MediaTypes::Serialization
+
+  allow_output_serializer(BookSerializer, only: %i[show])
+  allow_input_serializer(BookSerializer, only: %i[create])
+  freeze_io!
+
+  def show
+    book = Book.new
+    book.title = 'Everything, abridged'
+
+    render media: serialize_media(book), content_type: request.format.to_s
+  end
+
+  def create
+    json = deserialize(request, context: self) # does validation for us
+    puts json
   end
 end
 ```
 
-If you have normalized your resources (e.g. into `@resource`), you can add a `render_media` method to your
-`BaseController` and render resources like so:
+If you use [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html) you might want to convert the verified json data during deserialization:
 
 ```ruby
-class ApiController < ActionController::API
-  def render_media(**opts)
-    render media: serialize_media(@resource), content_type: request.format.to_s, **opts
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
+
+  output versions: [1, 2, 3] do |obj, version, context|
+    attribute :book do
+      link :self, href: context.book_url(obj) if version >= 3
+
+      attribute :title, obj.title
+      attribute :description, obj.description if version >= 2
+    end
+
+  input versions: [1, 2, 3] do |json, version, context|
+    book = Book.new
+    book.title = json['book']['title']
+    book.description = 'Not available'
+    book.description = json['book']['description'] if version >= 2
+
+    # Best practise is to only save in the controller.
+    book
+  end
+end
+
+class BookController < ActionController::API
+  include MediaTypes::Serialization
+
+  allow_output_serializer(BookSerializer, only: %i[show])
+  allow_input_serializer(BookSerializer, only: %i[create])
+  freeze_io!
+
+  def show
+    book = Book.new
+    book.title = 'Everything, abridged'
+
+    render media: serialize_media(book), content_type: request.format.to_s
+  end
+
+  def create
+    book = deserialize(request, context: self)
+    book.save!
+
+    render media: serialize_media(book), content_type request.format.to_s
   end
 end
 ```
 
-And then call `render_media` whenever you're ready to render.
+If you don't want to apply any input validation or deserialization you can use the `allow_all_input` method instead of `allow_input_serialization`.
 
-### HTML output
+### Raw output
 
-You can define HTML outputs for example by creating a serializer that accepts `text/html`. At this moment, there may
-only be one (1) active `text/html` serializer for each action; a single controller can have multiple registered, but 
-never for the same preconditions in `before_action` (because how else would it know which one to pick?).
+Sometimes you need to output raw data. This cannot be validated. You do this as follows:
 
-Use the `render` method to generate your HTML:
 ```ruby
-class Book::CoverHtmlSerializer < MediaTypes::Serialization::Base
-  # Tell the serializer that this accepts HTML, but this is also signaled by `to_html`
-  serializes_html
-  
-  def to_html
-    ApplicationController.render(
-      'serializers/book/cover',
-      assigns: {
-        title: extract_title,
-        image: resolve_file_url(covers.first&.version_url('small')),
-        description: extract_description,
-        language_links: language_links,
-      },
-      layout: false
-    )
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
+
+  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
+
+    "I'm a non-json output"
   end
-  
-  # Naturally you have to define extract_title, etc etc 
 end
 ```
 
-You can change the default `wrapper` / `to_html` implementation by setting:
+### Raw input
+
+You can do the same with input:
 
 ```ruby
-::MediaTypes::Serialization.html_wrapper_layout = '/path/to/wrapper/layout'
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
+
+  input_raw view: raw, version: 3 do |bytes, version, context|
+    book = Book.new
+    book.description = bytes
+
+    book
+  end
+end
 ```
 
-### API viewer
+### Remapping media type identifiers
 
-There is a special media type exposed by this gem at `::MediaTypes::Serialization::MEDIA_TYPE_API_VIEWER`. If you're
-using `rails` you'll want to register it. You can do so manually, or by `require`ing:
+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
-require 'media_types/serialization/media_type/register'
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
+
+  output versions: [1, 2, 3] do |obj, version, context|
+    attribute :book do
+      link :self, href: context.book_url(obj) if version >= 3
+
+      attribute :title, obj.title
+      attribute :description, obj.description if version >= 2
+    end
+  end
+  output_alias 'application/json' # maps application/json to to applicaton/vnd.acme.book.v1+json
+
+  input view: :create, versions: [1, 2, 3] do |json, version, context|
+    book = Book.new
+    book.title = json['book']['title']
+    book.description = 'Not available'
+    book.description = json['book']['description'] if version >= 2
+
+    # Make sure not to save here but only save in the controller
+    book
+  end
+  input_alias 'application/json', view: :create # maps application/json to to applicaton/vnd.acme.book.v1+json
 ```
 
-If you do so, the `.api_viewer` format becomes available for all actions that call into `render media:`.
+Validation will be done using the remapped validator. Aliasses map to version `nil` if that is available or `1` otherwise. It is not possible to configure this version.
 
-You can change the default `wrapper` implementation by setting:
+### 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.
+
+To enable the API viewer, use: `allow_api_viewer` in the controller.
 
 ```ruby
-::MediaTypes::Serialization.api_viewer_layout = '/path/to/wrapper/layout'
-```
+class BookController < ActionController::API
+  include MediaTypes::Serialization
 
-### Wrapping output
+  allow_api_viewer
 
-By convention, `index` views are wrapped in `_index: [items]`, `collection` views are wrapped in `_embedded: [items]`
-and `create` / no views are wrapped in `[ROOT_KEY]: item`. This is currently only enabled for `to_json` serialization
-but planned for `xml` as well.
+  allow_output_serializer(BookSerializer, only: %i[show])
+  allow_input_serializer(BookSerializer, only: %i[create])
+  freeze_io!
 
-This behaviour can not be turned of as of writing. However, you may _overwrite_ this behaviour via:
+  def show
+    book = Book.new
+    book.title = 'Everything, abridged'
 
-- `self.root_key(view:)`: to define the root key for a specific `view`
-- `self.wrap(serializer, view: nil)`: to define the wrapper for a specific `view` and/or `serializer`. For example, if
-  you never want to wrap anything, you could define:
-  ```ruby
-  def self.wrap(serializer, view: nil)
-    serializer
+    render media: serialize_media(book), content_type: request.format.to_s
   end
-  ```
 
-### Link header
+  def create
+    json = deserialize(request, context: self) # does validation for us
+    puts json
+  end
+end
+```
 
-You can use `to_link_header` to generate a header value for the `Link` header.
+You can also output custom HTML:
 
 ```ruby
-entries = @last_media_serializer.to_link_header
-if entries.present?
-  response.header[HEADER_LINK] = entries
+class BookSerializer < MediaTypes::Serialization::Base
+  validator BookValidator
+
+  output versions: [1, 2, 3] do |obj, version, context|
+    attribute :book do
+      link :self, href: context.book_url(obj) if version >= 3
+
+      attribute :title, obj.title
+      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
 ```
 
-If you want the link header to be different from the `_links`, you can implement `header_links(view:)` next to 
-`extract_links(view:)`. This will be called by the `to_link_header` function.
+#### Errors
 
-### Validation
-If you only have `json`/`xml`/structured data responses and you want to use [`media_types-validation`](https://github.com/XPBytes/media_types-validation) in conjunction with this gem, you can create a concern or add the following two functions to your base controller:
+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
-def render_media(resource = @resource, **opts)
-  serializer = serialize_media(resource)
-  render media: serializer, content_type: request.format.to_s, **opts
-  validate_media(serializer)
-end
+class BookController < ActionController::API
+  include MediaTypes::Serialization
 
-def validate_media(serializer = @last_media_serializer)
-  media_type = serializer.current_media_type
-  return true unless media_type && response_body
-  validate_json_with_media_type(serializer.to_hash, media_type: media_type)
+  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'
+
+    p.status_code :forbidden
+  end
+
+  freeze_io!
+
+  # ...
 end
 ```
 
-As long as the serializer has a `to_json` or `to_hash`, this will work -- but also means that the data will always be validate _as if_ it were json. This covers most use cases.
+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.
+
+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.
+
+Custom attributes can be added using the `p.attribute(name, value)` function.
 
 ### Related
 
-- [`MediaTypes`](https://github.com/SleeplessByte/media-types-ruby): :gem: Library to create media type definitions, schemes and validations
-- [`MediaTypes::Deserialization`](https://github.com/XPBytes/media_types-deserialization): :cyclone: Add media types supported deserialization using your favourite parser, and media type validation.
-- [`MediaTypes::Validation`](https://github.com/XPBytes/media_types-validation): :heavy_exclamation_mark: Response validations according to a media-type
+- [`MediaTypes`](https://github.com/SleeplessByte/media-types-ruby): :gem: Library to create media type validators.
+
+## API
+
+### Serializer definition
+
+These methods become available during class definition if you inherit from `MediaTypes::Serialization::Base`.
+
+#### `unvalidated( prefix )`
+
+Disabled validation for this serializer. Prefix is of the form `application/vnd.<organisation>.<name>`.
+
+Either unvalidated or validator must be used while defining a serializer.
+
+#### `validator( media_type_validator )`
+
+Enabled validation for this serializer using a [Media Type Validator](https://github.com/SleeplessByte/media-types-ruby).
+
+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.
+
+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.
+
+#### `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.
+
+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]`.
+
+#### `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.
+
+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.
+
+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.
+
+#### `input_raw( view:, version:, versions: ) do |bytes, version, context|`
+
+This has the same behavior as `input` but takes in raw data. Input is not validated.
+
+#### `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.
+
+#### `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.
+
+#### `disable_wildcards`
+
+Disables registering wildcard media types.
+
+### Serializer 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`.
+
+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.
+
+If `emit_header` is `true` the link will also be emitted as a http header.
+
+Returns the built up context so far.
+
+#### `index( array, serializer, version:, view: nil )`
+
+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 )`
+
+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.
+
+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.
+
+Returns the unmodified context.
+
+#### `emit`
+
+Can be added to the end of a block to fix up the return value to return the built up context so far.
+
+Returns the built up context so far.
+
+#### `object do`
+
+Runs a block in a new context and returns the result
+
+#### `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.
+
+### Controller definition
+
+These functions are available during the controller definition if you add `include MediaTypes::Serialization`.
+
+#### `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.
+
+Accepts the same filters as `before_action`.
+
+#### `allow_output_html( as: 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`.
+
+#### `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.
+
+Accepts the same filters as `before_action`.
+
+#### `allow_all_input( **filters )`
+
+Disables input deserialization. Running `deserialize` while allowing all input will result in an error being thrown.
+
+#### `not_acceptable_serializer( serializer )`
+
+Replaces the serializer used to render the error page when no media type could be negotiated using the `Accept` header.
+
+#### `unsupported_media_type_serializer( serializer )`
+
+Adds a serializer that can be used to render the error page when the client submits a body with a `Content-Type` that was not added to the whitelist using `allow_input_serialization`.
+
+#### `clear_unsupported_media_type_serializers!`
+
+Clears the list of serializers used to render the error when the client supplies non-valid input.
+
+#### `input_validation_failed_serializer( serializer )`
+
+Adds a serializer that can be used to render the error page when input validation fails.
+
+#### `clear_input_validation_failed_serializers!`
+
+Clears the list of serializers used to render the error when the client supplies non-valid input.
+
+#### `allow_api_viewer(serializer: MediaTypes::Serialization::Serializers::ApiViewer, **filter_opts)`
+
+Enables rendering the api viewer when adding the `api_viewer=last` query parameter to the url.
+
+#### `freeze_io!(**filter_opts)`
+
+Registers serialization and deserialization in the controller. This function must be called before using the controller.
+
+### Controller usage
+
+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:
+
+```ruby
+render_media do
+  serializer BookSerializer, book
+  serializer BooksSerializer do
+    [ book ]
+  end
+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.
+
+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.
+
+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.
+
+Due to the way this gem is implemented it is not possible to use instance variables (`@variable`) in the `render_media` do block.
+
+#### `deserialize( request )`
+
+Deserializes the request body using the configured input serializers and returns the deserialized object.
+
+Returns nil if no input body was given by the client.
+
+This method throws a `MediaTypes::Serialization::InputValidationFailedError` error if the incoming data does not conform to the specified schema.
+
+#### `deserialize!( request )`
+
+Does the same as `deserialize( request )` but gives the client an error page if no input was supplied.
+
+#### `resolve_serializer(request, identifier = nil, registration = @serialization_output_registration)`
+
+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
+# config/initializers/serialization.rb
+
+MediaTypes::Serialization::Serializers::CommonCSS.background = 'linear-gradient(245deg, #3a2f28 0%, #201a16 100%)'
+MediaTypes::Serialization::Serializers::CommonCSS.logo_width = 12
+MediaTypes::Serialization::Serializers::CommonCSS.logo_data = <<-HERE
+<svg height="150" width="500">
+  <ellipse cx="240" cy="100" rx="220" ry="30" style="fill:purple" />
+  <ellipse cx="220" cy="70" rx="190" ry="20" style="fill:lime" />
+  <ellipse cx="210" cy="45" rx="170" ry="15" style="fill:yellow" />
+</svg>
+HERE
+```
 
 ## Development