diff --git a/modules/swagger-codegen/src/main/resources/perl/ApiClient.mustache b/modules/swagger-codegen/src/main/resources/perl/ApiClient.mustache index ae8dce3d351..6e88d7967c2 100644 --- a/modules/swagger-codegen/src/main/resources/perl/ApiClient.mustache +++ b/modules/swagger-codegen/src/main/resources/perl/ApiClient.mustache @@ -290,13 +290,15 @@ sub select_header_content_type # @return string API key with the prefix sub get_api_key_with_prefix { - my ($self, $api_key) = @_; - 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}; - } else { - return $WWW::{{moduleName}}::Configuration::api_key->{$api_key}; - } -} + my ($self, $key_name) = @_; + + my $api_key = $WWW::{{moduleName}}::Configuration::api_key->{$key_name}; + + 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, diff --git a/modules/swagger-codegen/src/main/resources/perl/ApiFactory.mustache b/modules/swagger-codegen/src/main/resources/perl/ApiFactory.mustache index cb619091ca3..c38028fb37a 100644 --- a/modules/swagger-codegen/src/main/resources/perl/ApiFactory.mustache +++ b/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 { diff --git a/modules/swagger-codegen/src/main/resources/perl/README.md b/modules/swagger-codegen/src/main/resources/perl/README.md index 3cc2fda6528..16df3de6217 100644 --- a/modules/swagger-codegen/src/main/resources/perl/README.md +++ b/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 -authentication for each request. +This method does not exist! But if you add it to the class that consumes this +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 example: - - sub auth_setup_handler { - my ($self, %p) = @_; - $p{header_params}->{'X-TargetApp-apiKey'} = $api_key; - $p{header_params}->{'X-TargetApp-secretKey'} = $secret_key; - } + for communicating with the server. Just in case that's useful. ## 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 diff --git a/modules/swagger-codegen/src/main/resources/perl/Role.mustache b/modules/swagger-codegen/src/main/resources/perl/Role.mustache index 951f05bab74..4ece1bd092e 100644 --- a/modules/swagger-codegen/src/main/resources/perl/Role.mustache +++ b/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 -(by setting up attributes via the C keyword). They should be used by -C 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 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 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 -This method is NOT provided - you must write it yourself. Its task is to configure -authentication for each request. +This method does not exist! But if you add it to the class that consumes this +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 will be called on your C<$api> object and passed the +following parameters: =over 4 @@ -143,27 +201,20 @@ parameters. =item C -TODO. +TODO. Probably not necessary? =item C A reference to the C 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 already set as a default value. This method -returns (and optionally sets) the current value of C. +returns (and optionally sets, but only if the API client has not been +created yet) the current value of C. =head2 api_factory diff --git a/samples/client/petstore/perl/README.md b/samples/client/petstore/perl/README.md index a04d5a0aad6..1e0091fcc6b 100644 --- a/samples/client/petstore/perl/README.md +++ b/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 -authentication for each request. +This method does not exist! But if you add it to the class that consumes this +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 example: - - sub auth_setup_handler { - my ($self, %p) = @_; - $p{header_params}->{'X-TargetApp-apiKey'} = $api_key; - $p{header_params}->{'X-TargetApp-secretKey'} = $secret_key; - } + for communicating with the server. Just in case that's useful. ## 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 diff --git a/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiClient.pm b/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiClient.pm index d3568c812e4..e34fffe7848 100644 --- a/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiClient.pm +++ b/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiClient.pm @@ -290,13 +290,15 @@ sub select_header_content_type # @return string API key with the prefix sub get_api_key_with_prefix { - my ($self, $api_key) = @_; - 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}; - } else { - return $WWW::SwaggerClient::Configuration::api_key->{$api_key}; - } -} + my ($self, $key_name) = @_; + + my $api_key = $WWW::SwaggerClient::Configuration::api_key->{$key_name}; + + 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, diff --git a/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiFactory.pm b/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiFactory.pm index 77c23fdb2b3..b428e503b9e 100644 --- a/samples/client/petstore/perl/lib/WWW/SwaggerClient/ApiFactory.pm +++ b/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 { diff --git a/samples/client/petstore/perl/lib/WWW/SwaggerClient/Role.pm b/samples/client/petstore/perl/lib/WWW/SwaggerClient/Role.pm index 2b8969b3e3f..b66a6bd2e27 100644 --- a/samples/client/petstore/perl/lib/WWW/SwaggerClient/Role.pm +++ b/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 -(by setting up attributes via the C keyword). They should be used by -C 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 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 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 -This method is NOT provided - you must write it yourself. Its task is to configure -authentication for each request. +This method does not exist! But if you add it to the class that consumes this +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 will be called on your C<$api> object and passed the +following parameters: =over 4 @@ -143,27 +201,20 @@ parameters. =item C -TODO. +TODO. Probably not necessary? =item C A reference to the C 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 already set as a default value. This method -returns (and optionally sets) the current value of C. +returns (and optionally sets, but only if the API client has not been +created yet) the current value of C. =head2 api_factory