NAME

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

OVERVIEW

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

RENDER METHODS

   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.

       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.

   render_swagger
       This method is called automatically by Mojolicious::Plugin::Swagger2. The process is:

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

       2.  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.

       3.  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.

       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 "render_swagger" is called with the "200"
           status code, if not it will be called with a "500" status code.

       5.  "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.

STATUS CODES

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

   400
       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"
             },
             ...
           ]
         }

   500
       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"
             },
             ...
           ]
         }

   501
       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": "/"
             }
           ]
         }

   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#" }
                   }
                 }
               }
             }
           }
         }

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

AUTHOR

       Jan Henning Thorsen - "jhthorsen@cpan.org"