.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Swagger2::Guides::Render 3pm"
.TH Swagger2::Guides::Render 3pm "2016-04-17" "perl v5.22.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Swagger2::Guides::Render \- Details about the render process
.SH "OVERVIEW"
.IX Header "OVERVIEW"
This guide will show how to render data with Mojolicious::Plugin::Swagger2.
.SH "RENDER METHODS"
.IX Header "RENDER METHODS"
.SS "render"
.IX Subsection "render"
This is the standard 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.
.PP
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\*(R" and
you must call \*(L"render\*(R" in Mojolicious::Controller directly.
.SS "render_swagger"
.IX Subsection "render_swagger"
This method is called automatically by Mojolicious::Plugin::Swagger2. The
process is:
.IP "1." 4
A request hit your web server and gets passed on to one of the autogenerated
swagger routes.
.IP "2." 4
There is a check called to see if the given controller and action exists. If
this fail, \*(L"render_swagger\*(R" will be called with the \*(L"501\*(R" status code.
.IP "3." 4
Next the input data is parsed to see if the request is valid. If this fail,
\&\*(L"render_swagger\*(R" is called with the \*(L"400\*(R" status code.
.IP "4." 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\*(R" is called with
the \*(L"200\*(R" status code, if not it will be called with a \*(L"500\*(R" status code.
.IP "5." 4
\&\*(L"render_swagger\*(R" will by default generate a \s-1JSON\s0 response using
\&\*(L"render\*(R" in Mojolicious::Controller. For a different response type you need to
override \*(L"render_swagger\*(R". Since \*(L"render_swagger\*(R" is a \*(L"helper\*(R" it suffices
to redefine \*(L"render_swagger\*(R" as a helper once the
Mojolicious::Plugin::Swagger2 plugin is loaded. Example:
.Sp
.Vb 2
\&  package MyApp;
\&  use Some::XML::Library "toXML";
\&
\&  sub startup {
\&    my ($app) = @_;
\&
\&    $app\->helper(
\&      render_swagger => sub {
\&        my ($c, $err, $data, $status) = @_;
\&        $data = $err if %$err;
\&        return $c\->respond_to(
\&          xml => {text => toXML($data), status => $status},
\&          any => {ref $data ? (json => $data) : (data => $data), status => $status},
\&        );
\&      }
\&    );
\&  }
.Ve
.PP
As for the  \*(L"render\*(R" method above, there is nothing that prevents you from
calling \f(CW\*(C`/render_swagger\*(C'\fR 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.
.SH "STATUS CODES"
.IX Header "STATUS CODES"
.SS "200"
.IX Subsection "200"
The default \f(CW$status\fR is 200, unless the method handling the request sent back
another value. \f(CW%err\fR will be empty in this case.
.SS "400"
.IX Subsection "400"
This module will set \f(CW$status\fR to 400 on invalid input. \f(CW%err\fR then contains
a data structure describing the errors. The default is to render a \s-1JSON\s0
document, like this:
.PP
.Vb 9
\&  {
\&    "errors": [
\&      {
\&        "message": "string value found, but a integer is required",
\&        "path": "/limit"
\&      },
\&      ...
\&    ]
\&  }
.Ve
.SS "500"
.IX Subsection "500"
This module will set \f(CW$status\fR to 500 on invalid response from the handler.
\&\f(CW%err\fR then contains a data structure describing the errors. The default is
to render a \s-1JSON\s0 document, like this:
.PP
.Vb 9
\&  {
\&    "errors": [
\&      {
\&        "message": "is missing and it is required",
\&        "path": "/limit"
\&      },
\&      ...
\&    ]
\&  }
.Ve
.SS "501"
.IX Subsection "501"
This module will set \f(CW$status\fR to 501 if the given controller has not
implemented the required method. \f(CW%err\fR then contains a data structure
describing the errors. The default is to render a \s-1JSON\s0 document, like this:
.PP
.Vb 8
\&  {
\&    "errors": [
\&      {
\&        "message": "No handler defined.",
\&        "path": "/"
\&      }
\&    ]
\&  }
.Ve
.SS "Default error schema"
.IX Subsection "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:
.PP
.Vb 10
\&  {
\&    "paths":
\&      "/pets" : {
\&        "get" : {
\&          "responses" : {
\&            "default": {
\&              "description": "Default error.",
\&              "schema": { "$ref": "http://git.io/vcKD4#" }
\&            }
\&          }
\&        }
\&      }
\&    }
\&  }
.Ve
.PP
<http://git.io/vcKD4> can also be provided as a full \s-1URL:
\&\s0<https://raw.githubusercontent.com/jhthorsen/swagger2/master/lib/Swagger2/error.json>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jan Henning Thorsen \- \f(CW\*(C`jhthorsen@cpan.org\*(C'\fR