=head1 NAME

Swagger2::Guides::Render - Details about the render process

=head1 OVERVIEW

This guide will show how to render data with L<Mojolicious::Plugin::Swagger2>.

=head1 RENDER METHODS

=head2 render

This is the standard L<Mojolicious> render method. There is nothing that
prevents you from calling this manually from inside your actions, but doing
so will bypass the output validation code which is generated on the fly.

There is an exception to this rule though: If you want to render binary data,
then it won't make much sense to pass the data on to L</render_swagger> and
you must call L<Mojolicious::Controller/render> directly.

=head2 render_swagger

This method is called automatically by L<Mojolicious::Plugin::Swagger2>. The
process is:

=over 4

=item 1.

A request hit your web server and gets passed on to one of the autogenerated
swagger routes.

=item 2.

There is a check called to see if the given controller and action exists. If
this fail, L</render_swagger> will be called with the L</501> status code.

=item 3.

Next the input data is parsed to see if the request is valid. If this fail,
L</render_swagger> is called with the L</400> status code.

=item 4.

The specified method (action) is called with the validated data and a callback.
If the callback is called with response data, then the response data is parsed
and validated. If the response is valid, then L</render_swagger> is called with
the L</200> status code, if not it will be called with a L</500> status code.

=item 5.

L</render_swagger> will by default generate a JSON response using
L<Mojolicious::Controller/render>.

=back

As for the  L</render> method above, there is nothing that prevents you from
calling C</render_swagger> manually from inside your actions, but doing so will
bypass the output validation code which is generated on the fly. There should
not be a case when you need to call this method directly.


=head1 STATUS CODES

=head2 200

The default C<$status> is 200, unless the method handling the request sent back
another value. C<%err> will be empty in this case.

=head2 400

This module will set C<$status> to 400 on invalid input. C<%err> then contains
a data structure describing the errors. The default is to render a JSON
document, like this:

  {
    "errors": [
      {
        "message": "string value found, but a integer is required",
        "path": "/limit"
      },
      ...
    ]
  }

=head2 500

This module will set C<$status> to 500 on invalid response from the handler.
C<%err> then contains a data structure describing the errors. The default is
to render a JSON document, like this:

  {
    "errors": [
      {
        "message": "is missing and it is required",
        "path": "/limit"
      },
      ...
    ]
  }

=head2 501

This module will set C<$status> to 501 if the given controller has not
implemented the required method. C<%err> then contains a data structure
describing the errors. The default is to render a JSON document, like this:

  {
    "errors": [
      {
        "message": "No handler defined.",
        "path": "/"
      }
    ]
  }

=head2 Default error schema

The above statuses use the following error schema. It is general enough and so
far works well. Feel free to use it in your applications like this:

  {
    "paths":
      "/pets" : {
        "get" : {
          "responses" : {
            "default": {
              "description": "Default error.",
              "schema": { "$ref": "http://git.io/vcKD4#" }
            }
          }
        }
      }
    }
  }

L<http://git.io/vcKD4> can also be provided as a full URL:
L<https://raw.githubusercontent.com/jhthorsen/swagger2/master/lib/Swagger2/error.json>.

=head1 AUTHOR

Jan Henning Thorsen - C<jhthorsen@cpan.org>

=cut
