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 <https://github.com/jhthorsen/swagger2/blob/master/t/blog/api.json>

       •   Application <https://github.com/jhthorsen/swagger2/blob/master/t/blog/lib/Blog.pm>

       •   Controller <https://github.com/jhthorsen/swagger2/blob/master/t/blog/lib/Blog/Controller/Posts.pm>

       •   Tests <https://github.com/jhthorsen/swagger2/blob/master/t/authenticate.t>

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  <https://github.com/swagger-api/swagger-
       spec/blob/master/versions/2.0.md#operationObject>   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"

perl v5.22.1                                       2016-02-15                 Mojolicious::Plugin::Swagger2(3pm)