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

NAME

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

SYNOPSIS

package MyApp;
use Mojo::Base "Mojolicious";

sub startup {
  my $app = shift;
  $app->plugin(Swagger2 => {url => "data://MyApp/petstore.json"});
}

__DATA__
@@ petstore.json
{
  "swagger": "2.0",
  "info": {...},
  "host": "petstore.swagger.wordnik.com",
  "basePath": "/api",
  "paths": {
    "/pets": {
      "get": {...}
    }
  }
}

DESCRIPTION

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

Have a look at the "RESOURCES" for a complete reference to what is possible or look at Swagger2::Guides::Tutorial for an introduction.

RESOURCES

HOOKS

swagger_route_added

$app->hook(swagger_route_added => sub {
  my ($app, $r) = @_;
  my $op_spec = $r->pattern->defaults->{swagger_operation_spec};
  # ...
});

The "swagger_route_added" event will be emitted on the application object for every route that is added by this plugin. This can be useful if you want to do things like specifying a custom route name.

STASH VARIABLES

swagger

The Swagger2 object used to generate the routes is available as swagger from stash. Example code:

sub documentation {
  my ($c, $args, $cb);
  $c->$cb($c->stash('swagger')->pod->to_string, 200);
}

swagger_operation_spec

The Swagger specification for the current operation object is stored in the "swagger_operation_spec" stash variable.

sub list_pets {
  my ($c, $args, $cb);
  $c->app->log->info($c->stash("swagger_operation_spec")->{operationId});
  ...
}

ATTRIBUTES

url

Holds the URL to the swagger specification file.

HELPERS

dispatch_to_swagger

$bool = $c->dispatch_to_swagger(\%data);

This helper can be used to handle WebSocket requests with swagger. See Swagger2::Guides::WebSocket for details.

This helper is EXPERIMENTAL.

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 used to set a proper HTTP status code such as 200, 400 or 500.

See also Swagger2::Guides::Render for more information.

METHODS

register

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

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

%config can contain these parameters:

  • coerce

    This argument will be passed on to "coerce" in JSON::Validator.

  • ensure_swagger_response

    $app->plugin(swagger2 => {
  ensure_swagger_response => {
    exception => "Internal server error.",
    not_found => "Not found.",
  }
});

    Adds a before_render hook which will make sure "exception" and "not_found" responses are in JSON format. There is no need to specify "exception" and "not_found" if you are happy with the defaults.

  • route

    Need to hold a Mojolicious route object. See "Protected API" for an example.

    This parameter is optional.

  • spec_path

    Holds the location for where the specifiation can be served from. The default value is "/", relative to "basePath" in the specification. Can be disabled by setting this value to empty string.

  • validate

    A boolean value (default is true) that will cause your schema to be validated. This plugin will abort loading if the schema include errors

  • swagger

    A Swagger2 object. This can be useful if you want to keep use the specification to other things in your application. Example:

    use Swagger2;
my $swagger = Swagger2->new->load($url);
plugin Swagger2 => {swagger => $swagger2};
app->defaults(swagger_spec => $swagger->api_spec);

    Either this parameter or url need to be present.

  • url

    This will be used to construct a new Swagger2 object. The url can be anything that "load" in Swagger2 can handle.

    Either this parameter or swagger need to be present.

COPYRIGHT AND LICENSE

Copyright (C) 2014-2015, 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