/usr/share/perl5/Swagger2/Guides/Render.pod is in libswagger2-perl 0.73-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | =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
|