NAME

       Swagger2::Guides::ProtectedApi - Protected API Guide

OVERVIEW

       It is possible to protect your API: You can either use a "Custom route" or an "Around action hook". Both
       can serve the same purpose, but the around action hook can be customized for every API resource.

TUTORIAL

   Around action hook
       The "x-mojo-around-action" value is optional, but can hold the name of a method to call, which wraps
       around the autogenerated action which does input and output validation. This means that any data sent to
       the server is not yet converted into $input to your action.

       Here is an example method which match the "x-mojo-around-action" from "Swagger specification",
       "MyApp::authenticate_api_request":

         package MyApp;

         sub authenticate_api_request {
           my ($next, $c, $action_spec) = @_;

           # Go to the action if the Authorization header is valid
           return $next->($c) if $c->req->headers->authorization eq "s3cret!";

           # ...or render an error if not
           return $c->render_swagger(
             {errors => [{message => "Invalid authorization key", path => "/"}]},
             {},
             401
           );
         }

       "x-mojo-around-action" is also inherited from most levels, meaning that you define it globally for your
       whole API if you like:

         {
           "x-mojo-around-action": "MyApp::protect_any_resource",
           "paths": {
             "/pets": {
               "x-mojo-around-action": "MyApp::protect_any_method_under_foo",
               "get": {
                 "x-mojo-around-action": "MyApp::protect_just_this_resource"
               }
             }
           }
         }

   Custom route
         use Mojolicious::Lite;

         my $route = app->routes->under->to(
           cb => sub {
             my $c = shift;
             return 1 if $c->param('secret');
             return $c->render(json => {error => "Not authenticated"}, status => 401);
           }
         );

         plugin Swagger2 => {
           route => $route,
           url   => "data://api.json",
         };

         __DATA__
         @@ api.json
         {"swagger":"2.0", ...}

AUTHOR

       Jan Henning Thorsen - "jhthorsen@cpan.org"

perl v5.22.1                                       2016-02-15                Swagger2::Guides::ProtectedApi(3pm)