Swagger2::Guides::Render(3) 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. For a different response type you need to override ``render_swagger''. Since ``render_swagger'' is a ``helper'' it suffices to redefine ``render_swagger'' as a helper once the Mojolicious::Plugin::Swagger2 plugin is loaded. Example: 

  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},
        );
      }
    );
  }

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 - "[email protected]"

LAST SEARCHED