Swagger2::Guides::Render - Details about the render process
This guide will show how to render data with Mojolicious::Plugin::Swagger2.
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.
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 "render_swagger" and you must call "render" in Mojolicious::Controller directly.
This method is called automatically by Mojolicious::Plugin::Swagger2. The process is:
A request hit your web server and gets passed on to one of the autogenerated swagger routes.
There is a check called to see if the given controller and action exists. If this fail, "render_swagger" will be called with the "501" status code.
Next the input data is parsed to see if the request is valid. If this fail, "render_swagger" is called with the "400" status code.
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 "render_swagger" is called with the "200" status code, if not it will be called with a "500" status code.
"render_swagger" will by default generate a JSON response using "render" in Mojolicious::Controller.
As for the "render" method above, there is nothing that prevents you from calling /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.
/render_swagger
The default $status is 200, unless the method handling the request sent back another value. %err will be empty in this case.
$status
%err
This module will set $status to 400 on invalid input. %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" }, ... ] }
This module will set $status to 500 on invalid response from the handler. %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" }, ... ] }
This module will set $status to 501 if the given controller has not implemented the required method. %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": "/" } ] }
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#" } } } } } } }
http://git.io/vcKD4 can also be provided as a full URL: https://raw.githubusercontent.com/jhthorsen/swagger2/master/lib/Swagger2/error.json.
Jan Henning Thorsen - jhthorsen@cpan.org
jhthorsen@cpan.org
To install Swagger2, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Swagger2
CPAN shell
perl -MCPAN -e shell install Swagger2
For more information on module installation, please visit the detailed CPAN module installation guide.