More documentation, and clean up a couple of ragged edges

- added documentation for configuring authentication
- made auth_setup_handler() optional
- get_api_key_with_prefix() is more self-documenting

modules/swagger-codegen/src/main/resources/perl/ApiClient.mustache

@@ -290,12 +290,14 @@ sub select_header_content_type
 # @return string API key with the prefix
 sub get_api_key_with_prefix
 {
-    my ($self, $api_key) = @_;
+	my ($self, $key_name) = @_;
-    if ($WWW::{{moduleName}}::Configuration::api_key_prefix->{$api_key}) {
+
-        return $WWW::{{moduleName}}::Configuration::api_key_prefix->{$api_key}." ".$WWW::{{moduleName}}::Configuration::api_key->{$api_key};
+	my $api_key = $WWW::{{moduleName}}::Configuration::api_key->{$key_name};
-    } else {
+	
-        return $WWW::{{moduleName}}::Configuration::api_key->{$api_key};
+	return unless $api_key;
-    }
+	
+	my $prefix = $WWW::{{moduleName}}::Configuration::api_key_prefix->{$key_name};
+	return $prefix ? "$prefix $api_key" : $api_key;
 }	
 
 # update header and query param based on authentication setting
@@ -306,7 +308,7 @@ sub get_api_key_with_prefix
 sub update_params_for_auth {
     my ($self, $header_params, $query_params, $auth_settings) = @_;
     
-    # we can defer to the application
+    # we can defer to the application if the spec doesn't describe authentication
     if ($self->{auth_setup_handler_object}) {
     	$self->{auth_setup_handler_object}->auth_setup_handler(
     									api_client => $self,

modules/swagger-codegen/src/main/resources/perl/ApiFactory.mustache

@@ -61,6 +61,9 @@ my %_apis = map { $_ =~ /^WWW::{{moduleName}}::(.*)$/; $1 => $_ }
 		The method should implement the required auth policy, for example, by setting 
 		secret keys in the header, or username and password in the URL, etc.
 		
+		This is only necessary when the API specification itself does not describe 
+		authentication.
+		
 =cut	
 
 sub new {

modules/swagger-codegen/src/main/resources/perl/README.md

@@ -19,21 +19,15 @@ role.
 
         package MyApp;
         use Moose;
-        has [qw(username password)] => ( is => 'ro', required => 1, isa => 'Str' );
         with 'WWW::{{moduleName}}::Role';
-        sub auth_setup_handler {...}
         
         package main;
         
-        my $api = MyApp->new({username => $username, password => $password});
+        my $api = MyApp->new;
         
         my $pet = $api->get_pet_by_id(pet_id => $pet_id);
         
 
-Notice that you need to provide the code to accept the parameters passed in to `new()`
-(by setting up attributes via the `has` keyword). They should be used by 
-`auth_setup_handler()` to configure authentication (see below). 
-
 ## Structure of the library
 
 The library consists of a set of API classes, one for each endpoint. These APIs
@@ -50,14 +44,74 @@ factory object, should you need it.
 
 For documentation of all these methods, see AUTOMATIC DOCUMENTATION below.
 
+## Configuring authentication
+
+If your Swagger spec does not describe authentication, you can write an 
+`auth_setup_handler()` method in your base class to handle it (see below).
+
+In the normal case, the Swagger spec will describe what parameters are required 
+and where to put them. You just need to supply the authorization tokens. 
+
+These should go in the `WWW::{{moduleName}}::Configuration` namespace as follows. 
+Note these are all optional, and depend on the API you are accessing.
+
+- `$WWW::{{moduleName}}::Configuration::username`
+
+    String. The username for basic auth.
+
+- `$WWW::{{moduleName}}::Configuration::password`
+
+    String. The password for basic auth.
+
+- `$WWW::{{moduleName}}::Configuration::api_key`
+
+    Hashref. Keyed on the name of each key (there can be multiple tokens).
+
+            $WWW::{{moduleName}}::Configuration::api_key = {
+                    secretKey => 'aaaabbbbccccdddd',
+                    anotherKey => '1111222233334444',
+                    };
+
+- `$WWW::{{moduleName}}::Configuration::api_key_prefix`
+
+    Hashref. Keyed on the name of each key (there can be multiple tokens). Note not
+    all api keys require a prefix.
+
+            $WWW::{{moduleName}}::Configuration::api_key_prefix = {
+                    secretKey => 'string',
+                    anotherKey => 'same or some other string',
+                    };
+
+- `$WWW::{{moduleName}}::Configuration::access_token`
+
+    String. The OAuth access token. 
+
 # METHODS
 
 ## `auth_setup_handler()`
 
-This method is NOT provided - you must write it yourself. Its task is to configure 
+This method does not exist! But if you add it to the class that consumes this 
-authentication for each request. 
+role, it will be called to set up authentication. 
 
-The method is called on your `$api` object and passed the following parameters:
+        package MyApp;
+        use Moose;
+        
+        with 'WWW::{{moduleName}}::Role';
+        
+        sub auth_setup_handler {
+                my ($self, %p) = @_;
+                $p{header_params}->{'X-TargetApp-apiKey'} = $api_key;
+                $p{header_params}->{'X-TargetApp-secretKey'} = $secret_key;
+        }
+        
+        # somewhere else...
+        
+        my $api = MyApp->new;
+        
+        my $pet = $api->get_pet_by_id(pet_id => $pet_id);
+
+So, `auth_setup_handler()` will be called on your `$api` object and passed the 
+following parameters:
 
 - `header_params`
 
@@ -71,25 +125,18 @@ The method is called on your `$api` object and passed the following parameters:
 
 - `auth_settings`
 
-    TODO.
+    TODO. Probably not necessary?
 
 - `api_client`
 
     A reference to the `WWW::{{moduleName}}::ApiClient` object that is responsible 
-    for communicating with the server. 
+    for communicating with the server. Just in case that's useful. 
-
-For example: 
-
-        sub auth_setup_handler {
-                my ($self, %p) = @_;
-                $p{header_params}->{'X-TargetApp-apiKey'} = $api_key;
-                $p{header_params}->{'X-TargetApp-secretKey'} = $secret_key;
-        }
 
 ## base\_url
 
 The generated code has the `base_url` already set as a default value. This method 
-returns (and optionally sets) the current value of `base_url`.
+returns (and optionally sets, but only if the API client has not been 
+created yet) the current value of `base_url`.
 
 ## api\_factory
 

modules/swagger-codegen/src/main/resources/perl/Role.mustache

@@ -7,8 +7,6 @@ use Class::Inspector;
 use Log::Any qw($log);
 use WWW::{{moduleName}}::ApiFactory;
 
-requires 'auth_setup_handler';
-
 has base_url => ( is => 'ro',
 			 	  required => 0,
 			 	  isa => 'Str',
@@ -64,7 +62,8 @@ sub BUILD {
 
 sub _build_af {
 	my $self = shift;
-	my %args = ( auth_setup_handler_object => $self );
+	my %args;
+	$args{auth_setup_handler_object} = $self if $self->can('auth_setup_handler');
 	$args{base_url} = $self->base_url if $self->base_url;
 	return WWW::{{moduleName}}::ApiFactory->new(%args);
 }
@@ -90,20 +89,14 @@ role.
 
 	package MyApp;
 	use Moose;
-	has [qw(username password)] => ( is => 'ro', required => 1, isa => 'Str' );
 	with 'WWW::{{moduleName}}::Role';
-	sub auth_setup_handler {...}
 	
 	package main;
 	
-	my $api = MyApp->new({username => $username, password => $password});
+	my $api = MyApp->new;
 	
 	my $pet = $api->get_pet_by_id(pet_id => $pet_id);
 	
-Notice that you need to provide the code to accept the parameters passed in to C<new()>
-(by setting up attributes via the C<has> keyword). They should be used by 
-C<auth_setup_handler()> to configure authentication (see below). 
-
 =head2 Structure of the library
 
 The library consists of a set of API classes, one for each endpoint. These APIs
@@ -120,14 +113,79 @@ factory object, should you need it.
 
 For documentation of all these methods, see AUTOMATIC DOCUMENTATION below.
 
+=head2 Configuring authentication
+
+If your Swagger spec does not describe authentication, you can write an 
+C<auth_setup_handler()> method in your base class to handle it (see below).
+
+In the normal case, the Swagger spec will describe what parameters are required 
+and where to put them. You just need to supply the authorization tokens. 
+
+These should go in the C<WWW::{{moduleName}}::Configuration> namespace as follows. 
+Note these are all optional, and depend on the API you are accessing.
+
+=over 4
+
+=item C<$WWW::{{moduleName}}::Configuration::username>
+
+String. The username for basic auth.
+
+=item C<$WWW::{{moduleName}}::Configuration::password>
+
+String. The password for basic auth.
+
+=item C<$WWW::{{moduleName}}::Configuration::api_key>
+
+Hashref. Keyed on the name of each key (there can be multiple tokens).
+
+	$WWW::{{moduleName}}::Configuration::api_key = {
+		secretKey => 'aaaabbbbccccdddd',
+		anotherKey => '1111222233334444',
+		};
+
+=item C<$WWW::{{moduleName}}::Configuration::api_key_prefix>
+
+Hashref. Keyed on the name of each key (there can be multiple tokens). Note not
+all api keys require a prefix.
+
+	$WWW::{{moduleName}}::Configuration::api_key_prefix = {
+		secretKey => 'string',
+		anotherKey => 'same or some other string',
+		};
+
+=item C<$WWW::{{moduleName}}::Configuration::access_token>
+
+String. The OAuth access token. 
+
+=back
+
 =head1 METHODS
 
 =head2 C<auth_setup_handler()>
 
-This method is NOT provided - you must write it yourself. Its task is to configure 
+This method does not exist! But if you add it to the class that consumes this 
-authentication for each request. 
+role, it will be called to set up authentication. 
 
-The method is called on your C<$api> object and passed the following parameters:
+	package MyApp;
+	use Moose;
+	
+	with 'WWW::{{moduleName}}::Role';
+	
+	sub auth_setup_handler {
+		my ($self, %p) = @_;
+		$p{header_params}->{'X-TargetApp-apiKey'} = $api_key;
+		$p{header_params}->{'X-TargetApp-secretKey'} = $secret_key;
+	}
+	
+	# somewhere else...
+	
+	my $api = MyApp->new;
+	
+	my $pet = $api->get_pet_by_id(pet_id => $pet_id);
+
+
+So, C<auth_setup_handler()> will be called on your C<$api> object and passed the 
+following parameters:
 
 =over 4
 
@@ -143,27 +201,20 @@ parameters.
 
 =item C<auth_settings>
 
-TODO.
+TODO. Probably not necessary?
 
 =item C<api_client>
 
 A reference to the C<WWW::{{moduleName}}::ApiClient> object that is responsible 
-for communicating with the server. 
+for communicating with the server. Just in case that's useful. 
 
 =back
 
-For example: 
-
-	sub auth_setup_handler {
-		my ($self, %p) = @_;
-		$p{header_params}->{'X-TargetApp-apiKey'} = $api_key;
-		$p{header_params}->{'X-TargetApp-secretKey'} = $secret_key;
-	}
-
 =head2 base_url
 
 The generated code has the C<base_url> already set as a default value. This method 
-returns (and optionally sets) the current value of C<base_url>.
+returns (and optionally sets, but only if the API client has not been 
+created yet) the current value of C<base_url>.
 
 =head2 api_factory
 

samples/client/petstore/perl/README.md

@@ -19,21 +19,15 @@ role.
 
         package MyApp;
         use Moose;
-        has [qw(username password)] => ( is => 'ro', required => 1, isa => 'Str' );
         with 'WWW::SwaggerClient::Role';
-        sub auth_setup_handler {...}
         
         package main;
         
-        my $api = MyApp->new({username => $username, password => $password});
+        my $api = MyApp->new;
         
         my $pet = $api->get_pet_by_id(pet_id => $pet_id);
         
 
-Notice that you need to provide the code to accept the parameters passed in to `new()`
-(by setting up attributes via the `has` keyword). They should be used by 
-`auth_setup_handler()` to configure authentication (see below). 
-
 ## Structure of the library
 
 The library consists of a set of API classes, one for each endpoint. These APIs
@@ -50,14 +44,74 @@ factory object, should you need it.
 
 For documentation of all these methods, see AUTOMATIC DOCUMENTATION below.
 
+## Configuring authentication
+
+If your Swagger spec does not describe authentication, you can write an 
+`auth_setup_handler()` method in your base class to handle it (see below).
+
+In the normal case, the Swagger spec will describe what parameters are required 
+and where to put them. You just need to supply the authorization tokens. 
+
+These should go in the `WWW::SwaggerClient::Configuration` namespace as follows. 
+Note these are all optional, and depend on the API you are accessing.
+
+- `$WWW::SwaggerClient::Configuration::username`
+
+    String. The username for basic auth.
+
+- `$WWW::SwaggerClient::Configuration::password`
+
+    String. The password for basic auth.
+
+- `$WWW::SwaggerClient::Configuration::api_key`
+
+    Hashref. Keyed on the name of each key (there can be multiple tokens).
+
+            $WWW::SwaggerClient::Configuration::api_key = {
+                    secretKey => 'aaaabbbbccccdddd',
+                    anotherKey => '1111222233334444',
+                    };
+
+- `$WWW::SwaggerClient::Configuration::api_key_prefix`
+
+    Hashref. Keyed on the name of each key (there can be multiple tokens). Note not
+    all api keys require a prefix.
+
+            $WWW::SwaggerClient::Configuration::api_key_prefix = {
+                    secretKey => 'string',
+                    anotherKey => 'same or some other string',
+                    };
+
+- `$WWW::SwaggerClient::Configuration::access_token`
+
+    String. The OAuth access token. 
+
 # METHODS
 
 ## `auth_setup_handler()`
 
-This method is NOT provided - you must write it yourself. Its task is to configure 
+This method does not exist! But if you add it to the class that consumes this 
-authentication for each request. 
+role, it will be called to set up authentication. 
 
-The method is called on your `$api` object and passed the following parameters:
+        package MyApp;
+        use Moose;
+        
+        with 'WWW::SwaggerClient::Role';
+        
+        sub auth_setup_handler {
+                my ($self, %p) = @_;
+                $p{header_params}->{'X-TargetApp-apiKey'} = $api_key;
+                $p{header_params}->{'X-TargetApp-secretKey'} = $secret_key;
+        }
+        
+        # somewhere else...
+        
+        my $api = MyApp->new;
+        
+        my $pet = $api->get_pet_by_id(pet_id => $pet_id);
+
+So, `auth_setup_handler()` will be called on your `$api` object and passed the 
+following parameters:
 
 - `header_params`
 
@@ -71,25 +125,18 @@ The method is called on your `$api` object and passed the following parameters:
 
 - `auth_settings`
 
-    TODO.
+    TODO. Probably not necessary?
 
 - `api_client`
 
     A reference to the `WWW::SwaggerClient::ApiClient` object that is responsible 
-    for communicating with the server. 
+    for communicating with the server. Just in case that's useful. 
-
-For example: 
-
-        sub auth_setup_handler {
-                my ($self, %p) = @_;
-                $p{header_params}->{'X-TargetApp-apiKey'} = $api_key;
-                $p{header_params}->{'X-TargetApp-secretKey'} = $secret_key;
-        }
 
 ## base\_url
 
 The generated code has the `base_url` already set as a default value. This method 
-returns (and optionally sets) the current value of `base_url`.
+returns (and optionally sets, but only if the API client has not been 
+created yet) the current value of `base_url`.
 
 ## api\_factory
 

samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiClient.pm

@@ -290,12 +290,14 @@ sub select_header_content_type
 # @return string API key with the prefix
 sub get_api_key_with_prefix
 {
-    my ($self, $api_key) = @_;
+	my ($self, $key_name) = @_;
-    if ($WWW::SwaggerClient::Configuration::api_key_prefix->{$api_key}) {
+
-        return $WWW::SwaggerClient::Configuration::api_key_prefix->{$api_key}." ".$WWW::SwaggerClient::Configuration::api_key->{$api_key};
+	my $api_key = $WWW::SwaggerClient::Configuration::api_key->{$key_name};
-    } else {
+	
-        return $WWW::SwaggerClient::Configuration::api_key->{$api_key};
+	return unless $api_key;
-    }
+	
+	my $prefix = $WWW::SwaggerClient::Configuration::api_key_prefix->{$key_name};
+	return $prefix ? "$prefix $api_key" : $api_key;
 }	
 
 # update header and query param based on authentication setting
@@ -306,7 +308,7 @@ sub get_api_key_with_prefix
 sub update_params_for_auth {
     my ($self, $header_params, $query_params, $auth_settings) = @_;
     
-    # we can defer to the application
+    # we can defer to the application if the spec doesn't describe authentication
     if ($self->{auth_setup_handler_object}) {
     	$self->{auth_setup_handler_object}->auth_setup_handler(
     									api_client => $self,

samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiFactory.pm

@@ -61,6 +61,9 @@ my %_apis = map { $_ =~ /^WWW::SwaggerClient::(.*)$/; $1 => $_ }
 		The method should implement the required auth policy, for example, by setting 
 		secret keys in the header, or username and password in the URL, etc.
 		
+		This is only necessary when the API specification itself does not describe 
+		authentication.
+		
 =cut	
 
 sub new {

samples/client/petstore/perl/lib/WWW/SwaggerClient/Role.pm

@@ -7,8 +7,6 @@ use Class::Inspector;
 use Log::Any qw($log);
 use WWW::SwaggerClient::ApiFactory;
 
-requires 'auth_setup_handler';
-
 has base_url => ( is => 'ro',
 			 	  required => 0,
 			 	  isa => 'Str',
@@ -64,7 +62,8 @@ sub BUILD {
 
 sub _build_af {
 	my $self = shift;
-	my %args = ( auth_setup_handler_object => $self );
+	my %args;
+	$args{auth_setup_handler_object} = $self if $self->can('auth_setup_handler');
 	$args{base_url} = $self->base_url if $self->base_url;
 	return WWW::SwaggerClient::ApiFactory->new(%args);
 }
@@ -90,20 +89,14 @@ role.
 
 	package MyApp;
 	use Moose;
-	has [qw(username password)] => ( is => 'ro', required => 1, isa => 'Str' );
 	with 'WWW::SwaggerClient::Role';
-	sub auth_setup_handler {...}
 	
 	package main;
 	
-	my $api = MyApp->new({username => $username, password => $password});
+	my $api = MyApp->new;
 	
 	my $pet = $api->get_pet_by_id(pet_id => $pet_id);
 	
-Notice that you need to provide the code to accept the parameters passed in to C<new()>
-(by setting up attributes via the C<has> keyword). They should be used by 
-C<auth_setup_handler()> to configure authentication (see below). 
-
 =head2 Structure of the library
 
 The library consists of a set of API classes, one for each endpoint. These APIs
@@ -120,14 +113,79 @@ factory object, should you need it.
 
 For documentation of all these methods, see AUTOMATIC DOCUMENTATION below.
 
+=head2 Configuring authentication
+
+If your Swagger spec does not describe authentication, you can write an 
+C<auth_setup_handler()> method in your base class to handle it (see below).
+
+In the normal case, the Swagger spec will describe what parameters are required 
+and where to put them. You just need to supply the authorization tokens. 
+
+These should go in the C<WWW::SwaggerClient::Configuration> namespace as follows. 
+Note these are all optional, and depend on the API you are accessing.
+
+=over 4
+
+=item C<$WWW::SwaggerClient::Configuration::username>
+
+String. The username for basic auth.
+
+=item C<$WWW::SwaggerClient::Configuration::password>
+
+String. The password for basic auth.
+
+=item C<$WWW::SwaggerClient::Configuration::api_key>
+
+Hashref. Keyed on the name of each key (there can be multiple tokens).
+
+	$WWW::SwaggerClient::Configuration::api_key = {
+		secretKey => 'aaaabbbbccccdddd',
+		anotherKey => '1111222233334444',
+		};
+
+=item C<$WWW::SwaggerClient::Configuration::api_key_prefix>
+
+Hashref. Keyed on the name of each key (there can be multiple tokens). Note not
+all api keys require a prefix.
+
+	$WWW::SwaggerClient::Configuration::api_key_prefix = {
+		secretKey => 'string',
+		anotherKey => 'same or some other string',
+		};
+
+=item C<$WWW::SwaggerClient::Configuration::access_token>
+
+String. The OAuth access token. 
+
+=back
+
 =head1 METHODS
 
 =head2 C<auth_setup_handler()>
 
-This method is NOT provided - you must write it yourself. Its task is to configure 
+This method does not exist! But if you add it to the class that consumes this 
-authentication for each request. 
+role, it will be called to set up authentication. 
 
-The method is called on your C<$api> object and passed the following parameters:
+	package MyApp;
+	use Moose;
+	
+	with 'WWW::SwaggerClient::Role';
+	
+	sub auth_setup_handler {
+		my ($self, %p) = @_;
+		$p{header_params}->{'X-TargetApp-apiKey'} = $api_key;
+		$p{header_params}->{'X-TargetApp-secretKey'} = $secret_key;
+	}
+	
+	# somewhere else...
+	
+	my $api = MyApp->new;
+	
+	my $pet = $api->get_pet_by_id(pet_id => $pet_id);
+
+
+So, C<auth_setup_handler()> will be called on your C<$api> object and passed the 
+following parameters:
 
 =over 4
 
@@ -143,27 +201,20 @@ parameters.
 
 =item C<auth_settings>
 
-TODO.
+TODO. Probably not necessary?
 
 =item C<api_client>
 
 A reference to the C<WWW::SwaggerClient::ApiClient> object that is responsible 
-for communicating with the server. 
+for communicating with the server. Just in case that's useful. 
 
 =back
 
-For example: 
-
-	sub auth_setup_handler {
-		my ($self, %p) = @_;
-		$p{header_params}->{'X-TargetApp-apiKey'} = $api_key;
-		$p{header_params}->{'X-TargetApp-secretKey'} = $secret_key;
-	}
-
 =head2 base_url
 
 The generated code has the C<base_url> already set as a default value. This method 
-returns (and optionally sets) the current value of C<base_url>.
+returns (and optionally sets, but only if the API client has not been 
+created yet) the current value of C<base_url>.
 
 =head2 api_factory