Implement changes for API authentication and Swagger UI (#541)

* initial token-based-api login handler

* add token schema and validation

* initial import of pyro3d api code

* basic Swagger spec support

* Merge in working copy of API/Device.pm

* Fix some error handling for API/Device.pm

* Break out utility functions into separate file, to allow other api portions to use

* Add NodeIP support.

* Add nodeip plugin to config

* remove double define of "plugin:" (#448)

disclaimer: i did not test this is any way, came across it when looking for something else.

* only AuthZ header for api use, and alway regen key on login

* use RFC7235

* workaround for Swagger plugin weird response body

* do not autodiscover swagger routes

* code formatting only

* move api util to utils area

* initial full swagger spec for nodeip search

* add api user role and fix api auth failure response

* update version of swagger-ui to 3.20.3

* add more openapi defs

* fixes to SQL and api spec

* clean up subs

* improvements to login/logout for API

* make api logout work

* add openapi tags to group operations

* allow api params to be generated from DBIC schema spec

* remove API calls for nodes and devices

* remove some poor assumptions about api calls

* tidy up

* remove DDP

* make login and logout similar

* example of api call being handled by ajax call

* make the branch authonly

lib/App/Netdisco/Web.pm

@@ -5,6 +5,7 @@ use Dancer::Plugin::Ajax;
 
 use Dancer::Plugin::DBIC;
 use Dancer::Plugin::Auth::Extensible;
+use Dancer::Plugin::Swagger;
 
 use URI ();
 use Socket6 (); # to ensure dependency is met
@@ -75,6 +76,28 @@ eval {
 };
 Dancer::Session::Cookie::init(session);
 
+# setup for swagger API
+my $swagger = Dancer::Plugin::Swagger->instance->doc;
+$swagger->{schemes} = ['http','https'];
+$swagger->{consumes} = 'application/json';
+$swagger->{produces} = 'application/json';
+$swagger->{tags} = [
+  {name => 'Global'},
+  {name => 'Devices',
+    description => 'Operations relating to Devices (switches, routers, etc)'},
+  {name => 'Nodes',
+    description => 'Operations relating to Nodes (end-stations such as printers)'},
+  {name => 'NodeIPs',
+    description => 'Operations relating to MAC-IP mappings (IPv4 ARP and IPv6 Neighbors)'},
+];
+$swagger->{securityDefinitions} = {
+  APIKeyHeader =>
+    { type => 'apiKey', name => 'Authorization', in => 'header' },
+  BasicAuth =>
+    { type => 'basic'  },
+};
+$swagger->{security} = [ { APIKeyHeader => [] } ];
+
 # workaround for https://github.com/PerlDancer/Dancer/issues/935
 hook after_error_render => sub { setting('layout' => 'main') };
 
@@ -182,6 +205,16 @@ hook 'before_template' => sub {
     $Template::Stash::PRIVATE = undef;
 };
 
+# workaround for Swagger plugin weird response body
+hook 'after' => sub {
+    my $r = shift; # a Dancer::Response
+
+    if (request->path eq '/swagger.json') {
+        $r->content( to_json( $r->content ) );
+        header('Content-Type' => 'application/json');
+    }
+};
+
 # remove empty lines from CSV response
 # this makes writing templates much more straightforward!
 hook 'after' => sub {