=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</401> 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 Same as for the L</render> method above, 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 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