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"