/ 
Swagger2-0.14
River stage zero No dependents
/ Mojolicious::Plugin::Swagger2

NAME

Mojolicious::Plugin::Swagger2 - Mojolicious plugin for Swagger2

DESCRIPTION

Mojolicious::Plugin::Swagger2 is Mojolicious::Plugin that add routes and input/output validation to your Mojolicious application.

SYNOPSIS

Swagger specification

The input "url" to given as argument to the plugin need to point to a valid swagger document.

---
swagger: 2.0
basePath: /api
paths:
  /foo:
    get:
      operationId: listPets
      parameters: [ ... ]
      responses:
        200: { ... }

Application

The application need to load the Mojolicious::Plugin::Swagger2 plugin, with a URL to the specification and a controller namespace. The plugin will then add all the routes defined in the "Swagger specification".

use Mojolicious::Lite;

plugin Swagger2 => {
  url => app->home->rel_file("api.yaml"),
  controller => "MyApp::Controller::Api",
};

app->start;

Controller

The method names defined in the controller will be a decamelized version of operationId with the HTTP method at the end.

The example "Swagger specification" above, will result in list_pets_get() in the controller below to be called. This method will receive the current Mojolicious::Controller object, input arguments and a callback. The callback should be called with a HTTP status code, and a data structure which will be validated and serialized back to the user agent.

package MyApp::Controller::Api;

sub list_pets_get {
  my ($c, $args, $cb) = @_;
  $c->$cb({ foo => 123 }, 200);
}

ATTRIBUTES

controller

Holds a class name, which is used to dispatch the request to.

url

Holds the URL to the swagger specification file.

HELPERS

render_swagger

$c->render_swagger(\%err, \%data, $status);

This method is used to render %data from the controller method. The %err hash will be empty on success, but can contain input/output validation errors. $status is the HTTP status code to use:

  • 200

    The default $status is 200, unless the controller sent back any 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:

    {
  "valid": false,
  "errors": [
    {
      "message": "string value found, but a integer is required",
      "property": "$.limit"
    },
    ...
  ]
}

  • 500

    This module will set $status to 500 on invalid response from the controller. %err then contains a data structure describing the errors. The default is to render a JSON document, like this:

    {
  "valid": false,
  "errors": [
    {
      "message": "is missing and it is required",
      "property": "$.foo"
    },
    ...
  ]
}

  • 501

    This module will set $status to 501 if the "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:

    {
  "valid": false,
  "errors": [
    {
      "message": "No handler defined.",
      "property": null
    }
  ]
}

METHODS

register

$self->register($app, \%config);

This method is called when this plugin is registered in the Mojolicious application.

COPYRIGHT AND LICENSE

Copyright (C) 2014, Jan Henning Thorsen

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

AUTHOR

Jan Henning Thorsen - jhthorsen@cpan.org