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

• Swagger2::Guides::Tutorial - Tutorial for this plugin

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

• Swagger2::Guides::ProtectedApi - Protected API Guide

• Swagger2::Guides::CustomPlaceholder - Custom placeholder for your routes

• Swagger spec

• Application

• Controller

• Tests

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.

• 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

  CAVEAT! There is an issue with YAML and booleans, so YAML specs might fail even when they are correct. See https://github.com/jhthorsen/swagger2/issues/39.

• 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

cpanm Swagger2

perl -MCPAN -e shell
install Swagger2