Skip to content

Commit 8027dc8

Browse files
wing328wing328
committed
Merge pull request swagger-api#2400 from wing328/perl_getting_start
[Perl] add "Getting Started" section for Perl documentation
2 parents 2b3b2ae + 67e4b6b commit 8027dc8

File tree

7 files changed

+168
-85
lines changed

7 files changed

+168
-85
lines changed

‎modules/swagger-codegen/src/main/resources/perl/README.mustache

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -232,6 +232,47 @@ To load the models:
232232
{{/model}}{{/models}}
233233
````
234234

235+
# GETTING STARTED
236+
Put the Perl SDK under the 'lib' folder in your project directory, then run the following
237+
```perl
238+
#!/usr/bin/perl
239+
use lib 'lib';
240+
use strict;
241+
use warnings;
242+
# load the API package
243+
{{#apiInfo}}{{#apis}}use {{moduleName}}::{{classname}};
244+
{{/apis}}{{/apiInfo}}
245+
# load the models
246+
{{#models}}{{#model}}use {{moduleName}}::Object::{{classname}};
247+
{{/model}}{{/models}}
248+
# for displaying the API response data
249+
use Data::Dumper;
250+
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}{{#hasAuthMethods}}{{#authMethods}}{{#isBasic}}
251+
# Configure HTTP basic authorization: {{{name}}}
252+
{{{moduleName}}}::Configuration::username = 'YOUR_USERNAME';
253+
{{{moduleName}}}::Configuration::password = 'YOUR_PASSWORD';{{/isBasic}}{{#isApiKey}}
254+
# Configure API key authorization: {{{name}}}
255+
{{{moduleName}}}::Configuration::api_key->{'{{{keyParamName}}}'} = 'YOUR_API_KEY';
256+
# uncomment below to setup prefix (e.g. BEARER) for API key, if needed
257+
#{{{moduleName}}}::Configuration::api_key_prefix->{'{{{keyParamName}}}'} = 'BEARER';{{/isApiKey}}{{#isOAuth}}
258+
# Configure OAuth2 access token for authorization: {{{name}}}
259+
{{{moduleName}}}::Configuration::access_token = 'YOUR_ACCESS_TOKEN';{{/isOAuth}}{{/authMethods}}
260+
{{/hasAuthMethods}}
261+
262+
my $api_instance = {{moduleName}}::{{classname}}->new();
263+
{{#allParams}}my ${{paramName}} = {{#isListContainer}}({{/isListContainer}}{{#isBodyParam}}{{{moduleName}}}::Object::{{dataType}}->new(){{/isBodyParam}}{{^isBodyParam}}{{{example}}}{{/isBodyParam}}{{#isListContainer}}){{/isListContainer}}; # {{{dataType}}} | {{{description}}}
264+
{{/allParams}}
265+
266+
eval {
267+
{{#returnType}}my $result = {{/returnType}}$api_instance->{{{operationId}}}({{#allParams}}{{paramName}} => ${{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}});{{#returnType}}
268+
print Dumper($result);{{/returnType}}
269+
};
270+
if ($@) {
271+
warn "Exception when calling {{classname}}->{{operationId}}: $@\n";
272+
}
273+
{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
274+
```
275+
235276
# DOCUMENTATION FOR API ENDPOINTS
236277

237278
All URIs are relative to *{{basePath}}*

‎modules/swagger-codegen/src/main/resources/perl/api_doc.mustache

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,12 +37,12 @@ use Data::Dumper;
3737
{{{moduleName}}}::Configuration::access_token = 'YOUR_ACCESS_TOKEN';{{/isOAuth}}{{/authMethods}}
3838
{{/hasAuthMethods}}
3939

40-
my $api = {{moduleName}}::{{classname}}->new();
41-
{{#allParams}}my ${{paramName}} = {{#isListContainer}}({{/isListContainer}}{{#isBodyParam}}{{{moduleName}}}::Object::{{dataType}}->new(){{/isBodyParam}}{{^isBodyParam}}{{{example}}}{{/isBodyParam}}{{#isListContainer}}){{/isListContainer}}; # [{{{dataType}}}] {{description}}
40+
my $api_instance = {{moduleName}}::{{classname}}->new();
41+
{{#allParams}}my ${{paramName}} = {{#isListContainer}}({{/isListContainer}}{{#isBodyParam}}{{{moduleName}}}::Object::{{dataType}}->new(){{/isBodyParam}}{{^isBodyParam}}{{{example}}}{{/isBodyParam}}{{#isListContainer}}){{/isListContainer}}; # {{{dataType}}} | {{{description}}}
4242
{{/allParams}}
4343

4444
eval {
45-
{{#returnType}}my $result = {{/returnType}}$api->{{{operationId}}}({{#allParams}}{{paramName}} => ${{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}});{{#returnType}}
45+
{{#returnType}}my $result = {{/returnType}}$api_instance->{{{operationId}}}({{#allParams}}{{paramName}} => ${{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}});{{#returnType}}
4646
print Dumper($result);{{/returnType}}
4747
};
4848
if ($@) {

‎samples/client/petstore/perl/README.md

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ WWW::SwaggerClient::Role - a Moose role for the Swagger Petstore
88

99
Automatically generated by the Perl Swagger Codegen project:
1010

11-
- Build date: 2016-03-17T14:27:04.268+08:00
11+
- Build date: 2016-03-17T15:41:15.325+08:00
1212
- Build package: class io.swagger.codegen.languages.PerlClientCodegen
1313
- Codegen version:
1414

@@ -243,6 +243,48 @@ use WWW::SwaggerClient::Object::User;
243243

244244
````
245245

246+
# GETTING STARTED
247+
Put the Perl SDK under the 'lib' folder in your project directory, then run the following
248+
```perl
249+
#!/usr/bin/perl
250+
use lib 'lib';
251+
use strict;
252+
use warnings;
253+
# load the API package
254+
use WWW::SwaggerClient::PetApi;
255+
use WWW::SwaggerClient::StoreApi;
256+
use WWW::SwaggerClient::UserApi;
257+
258+
# load the models
259+
use WWW::SwaggerClient::Object::Category;
260+
use WWW::SwaggerClient::Object::InlineResponse200;
261+
use WWW::SwaggerClient::Object::Model200Response;
262+
use WWW::SwaggerClient::Object::ModelReturn;
263+
use WWW::SwaggerClient::Object::Name;
264+
use WWW::SwaggerClient::Object::Order;
265+
use WWW::SwaggerClient::Object::Pet;
266+
use WWW::SwaggerClient::Object::SpecialModelName;
267+
use WWW::SwaggerClient::Object::Tag;
268+
use WWW::SwaggerClient::Object::User;
269+
270+
# for displaying the API response data
271+
use Data::Dumper;
272+
273+
# Configure OAuth2 access token for authorization: petstore_auth
274+
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
275+
276+
my $api_instance = WWW::SwaggerClient::PetApi->new();
277+
my $body = WWW::SwaggerClient::Object::Pet->new(); # Pet | Pet object that needs to be added to the store
278+
279+
eval {
280+
$api_instance->add_pet(body => $body);
281+
};
282+
if ($@) {
283+
warn "Exception when calling PetApi->add_pet: $@\n";
284+
}
285+
286+
```
287+
246288
# DOCUMENTATION FOR API ENDPOINTS
247289

248290
All URIs are relative to *http://petstore.swagger.io/v2*

‎samples/client/petstore/perl/docs/PetApi.md

Lines changed: 38 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,11 @@ use Data::Dumper;
3636
# Configure OAuth2 access token for authorization: petstore_auth
3737
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
3838

39-
my $api = WWW::SwaggerClient::PetApi->new();
40-
my $body = WWW::SwaggerClient::Object::Pet->new(); # [Pet] Pet object that needs to be added to the store
39+
my $api_instance = WWW::SwaggerClient::PetApi->new();
40+
my $body = WWW::SwaggerClient::Object::Pet->new(); # Pet | Pet object that needs to be added to the store
4141

4242
eval {
43-
$api->add_pet(body => $body);
43+
$api_instance->add_pet(body => $body);
4444
};
4545
if ($@) {
4646
warn "Exception when calling PetApi->add_pet: $@\n";
@@ -82,11 +82,11 @@ use Data::Dumper;
8282
# Configure OAuth2 access token for authorization: petstore_auth
8383
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
8484

85-
my $api = WWW::SwaggerClient::PetApi->new();
86-
my $body = WWW::SwaggerClient::Object::string->new(); # [string] Pet object in the form of byte array
85+
my $api_instance = WWW::SwaggerClient::PetApi->new();
86+
my $body = WWW::SwaggerClient::Object::string->new(); # string | Pet object in the form of byte array
8787

8888
eval {
89-
$api->add_pet_using_byte_array(body => $body);
89+
$api_instance->add_pet_using_byte_array(body => $body);
9090
};
9191
if ($@) {
9292
warn "Exception when calling PetApi->add_pet_using_byte_array: $@\n";
@@ -128,12 +128,12 @@ use Data::Dumper;
128128
# Configure OAuth2 access token for authorization: petstore_auth
129129
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
130130

131-
my $api = WWW::SwaggerClient::PetApi->new();
132-
my $pet_id = 789; # [int] Pet id to delete
133-
my $api_key = 'api_key_example'; # [string]
131+
my $api_instance = WWW::SwaggerClient::PetApi->new();
132+
my $pet_id = 789; # int | Pet id to delete
133+
my $api_key = 'api_key_example'; # string |
134134

135135
eval {
136-
$api->delete_pet(pet_id => $pet_id, api_key => $api_key);
136+
$api_instance->delete_pet(pet_id => $pet_id, api_key => $api_key);
137137
};
138138
if ($@) {
139139
warn "Exception when calling PetApi->delete_pet: $@\n";
@@ -176,11 +176,11 @@ use Data::Dumper;
176176
# Configure OAuth2 access token for authorization: petstore_auth
177177
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
178178

179-
my $api = WWW::SwaggerClient::PetApi->new();
180-
my $status = (); # [ARRAY[string]] Status values that need to be considered for query
179+
my $api_instance = WWW::SwaggerClient::PetApi->new();
180+
my $status = (); # ARRAY[string] | Status values that need to be considered for query
181181

182182
eval {
183-
my $result = $api->find_pets_by_status(status => $status);
183+
my $result = $api_instance->find_pets_by_status(status => $status);
184184
print Dumper($result);
185185
};
186186
if ($@) {
@@ -223,11 +223,11 @@ use Data::Dumper;
223223
# Configure OAuth2 access token for authorization: petstore_auth
224224
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
225225

226-
my $api = WWW::SwaggerClient::PetApi->new();
227-
my $tags = (); # [ARRAY[string]] Tags to filter by
226+
my $api_instance = WWW::SwaggerClient::PetApi->new();
227+
my $tags = (); # ARRAY[string] | Tags to filter by
228228

229229
eval {
230-
my $result = $api->find_pets_by_tags(tags => $tags);
230+
my $result = $api_instance->find_pets_by_tags(tags => $tags);
231231
print Dumper($result);
232232
};
233233
if ($@) {
@@ -274,11 +274,11 @@ WWW::SwaggerClient::Configuration::api_key->{'api_key'} = 'YOUR_API_KEY';
274274
# Configure OAuth2 access token for authorization: petstore_auth
275275
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
276276

277-
my $api = WWW::SwaggerClient::PetApi->new();
278-
my $pet_id = 789; # [int] ID of pet that needs to be fetched
277+
my $api_instance = WWW::SwaggerClient::PetApi->new();
278+
my $pet_id = 789; # int | ID of pet that needs to be fetched
279279

280280
eval {
281-
my $result = $api->get_pet_by_id(pet_id => $pet_id);
281+
my $result = $api_instance->get_pet_by_id(pet_id => $pet_id);
282282
print Dumper($result);
283283
};
284284
if ($@) {
@@ -325,11 +325,11 @@ WWW::SwaggerClient::Configuration::api_key->{'api_key'} = 'YOUR_API_KEY';
325325
# Configure OAuth2 access token for authorization: petstore_auth
326326
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
327327

328-
my $api = WWW::SwaggerClient::PetApi->new();
329-
my $pet_id = 789; # [int] ID of pet that needs to be fetched
328+
my $api_instance = WWW::SwaggerClient::PetApi->new();
329+
my $pet_id = 789; # int | ID of pet that needs to be fetched
330330

331331
eval {
332-
my $result = $api->get_pet_by_id_in_object(pet_id => $pet_id);
332+
my $result = $api_instance->get_pet_by_id_in_object(pet_id => $pet_id);
333333
print Dumper($result);
334334
};
335335
if ($@) {
@@ -376,11 +376,11 @@ WWW::SwaggerClient::Configuration::api_key->{'api_key'} = 'YOUR_API_KEY';
376376
# Configure OAuth2 access token for authorization: petstore_auth
377377
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
378378

379-
my $api = WWW::SwaggerClient::PetApi->new();
380-
my $pet_id = 789; # [int] ID of pet that needs to be fetched
379+
my $api_instance = WWW::SwaggerClient::PetApi->new();
380+
my $pet_id = 789; # int | ID of pet that needs to be fetched
381381

382382
eval {
383-
my $result = $api->pet_pet_idtesting_byte_arraytrue_get(pet_id => $pet_id);
383+
my $result = $api_instance->pet_pet_idtesting_byte_arraytrue_get(pet_id => $pet_id);
384384
print Dumper($result);
385385
};
386386
if ($@) {
@@ -423,11 +423,11 @@ use Data::Dumper;
423423
# Configure OAuth2 access token for authorization: petstore_auth
424424
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
425425

426-
my $api = WWW::SwaggerClient::PetApi->new();
427-
my $body = WWW::SwaggerClient::Object::Pet->new(); # [Pet] Pet object that needs to be added to the store
426+
my $api_instance = WWW::SwaggerClient::PetApi->new();
427+
my $body = WWW::SwaggerClient::Object::Pet->new(); # Pet | Pet object that needs to be added to the store
428428

429429
eval {
430-
$api->update_pet(body => $body);
430+
$api_instance->update_pet(body => $body);
431431
};
432432
if ($@) {
433433
warn "Exception when calling PetApi->update_pet: $@\n";
@@ -469,13 +469,13 @@ use Data::Dumper;
469469
# Configure OAuth2 access token for authorization: petstore_auth
470470
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
471471

472-
my $api = WWW::SwaggerClient::PetApi->new();
473-
my $pet_id = 'pet_id_example'; # [string] ID of pet that needs to be updated
474-
my $name = 'name_example'; # [string] Updated name of the pet
475-
my $status = 'status_example'; # [string] Updated status of the pet
472+
my $api_instance = WWW::SwaggerClient::PetApi->new();
473+
my $pet_id = 'pet_id_example'; # string | ID of pet that needs to be updated
474+
my $name = 'name_example'; # string | Updated name of the pet
475+
my $status = 'status_example'; # string | Updated status of the pet
476476

477477
eval {
478-
$api->update_pet_with_form(pet_id => $pet_id, name => $name, status => $status);
478+
$api_instance->update_pet_with_form(pet_id => $pet_id, name => $name, status => $status);
479479
};
480480
if ($@) {
481481
warn "Exception when calling PetApi->update_pet_with_form: $@\n";
@@ -519,13 +519,13 @@ use Data::Dumper;
519519
# Configure OAuth2 access token for authorization: petstore_auth
520520
WWW::SwaggerClient::Configuration::access_token = 'YOUR_ACCESS_TOKEN';
521521

522-
my $api = WWW::SwaggerClient::PetApi->new();
523-
my $pet_id = 789; # [int] ID of pet to update
524-
my $additional_metadata = 'additional_metadata_example'; # [string] Additional data to pass to server
525-
my $file = '/path/to/file.txt'; # [File] file to upload
522+
my $api_instance = WWW::SwaggerClient::PetApi->new();
523+
my $pet_id = 789; # int | ID of pet to update
524+
my $additional_metadata = 'additional_metadata_example'; # string | Additional data to pass to server
525+
my $file = '/path/to/file.txt'; # File | file to upload
526526

527527
eval {
528-
$api->upload_file(pet_id => $pet_id, additional_metadata => $additional_metadata, file => $file);
528+
$api_instance->upload_file(pet_id => $pet_id, additional_metadata => $additional_metadata, file => $file);
529529
};
530530
if ($@) {
531531
warn "Exception when calling PetApi->upload_file: $@\n";

‎samples/client/petstore/perl/docs/StoreApi.md

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,11 @@ For valid response try integer IDs with value < 1000. Anything above 1000 or non
2828
```perl
2929
use Data::Dumper;
3030

31-
my $api = WWW::SwaggerClient::StoreApi->new();
32-
my $order_id = 'order_id_example'; # [string] ID of the order that needs to be deleted
31+
my $api_instance = WWW::SwaggerClient::StoreApi->new();
32+
my $order_id = 'order_id_example'; # string | ID of the order that needs to be deleted
3333

3434
eval {
35-
$api->delete_order(order_id => $order_id);
35+
$api_instance->delete_order(order_id => $order_id);
3636
};
3737
if ($@) {
3838
warn "Exception when calling StoreApi->delete_order: $@\n";
@@ -80,11 +80,11 @@ WWW::SwaggerClient::Configuration::api_key->{'x-test_api_client_secret'} = 'YOUR
8080
# uncomment below to setup prefix (e.g. BEARER) for API key, if needed
8181
#WWW::SwaggerClient::Configuration::api_key_prefix->{'x-test_api_client_secret'} = "BEARER";
8282

83-
my $api = WWW::SwaggerClient::StoreApi->new();
84-
my $status = 'status_example'; # [string] Status value that needs to be considered for query
83+
my $api_instance = WWW::SwaggerClient::StoreApi->new();
84+
my $status = 'status_example'; # string | Status value that needs to be considered for query
8585

8686
eval {
87-
my $result = $api->find_orders_by_status(status => $status);
87+
my $result = $api_instance->find_orders_by_status(status => $status);
8888
print Dumper($result);
8989
};
9090
if ($@) {
@@ -129,10 +129,10 @@ WWW::SwaggerClient::Configuration::api_key->{'api_key'} = 'YOUR_API_KEY';
129129
# uncomment below to setup prefix (e.g. BEARER) for API key, if needed
130130
#WWW::SwaggerClient::Configuration::api_key_prefix->{'api_key'} = "BEARER";
131131

132-
my $api = WWW::SwaggerClient::StoreApi->new();
132+
my $api_instance = WWW::SwaggerClient::StoreApi->new();
133133

134134
eval {
135-
my $result = $api->get_inventory();
135+
my $result = $api_instance->get_inventory();
136136
print Dumper($result);
137137
};
138138
if ($@) {
@@ -174,10 +174,10 @@ WWW::SwaggerClient::Configuration::api_key->{'api_key'} = 'YOUR_API_KEY';
174174
# uncomment below to setup prefix (e.g. BEARER) for API key, if needed
175175
#WWW::SwaggerClient::Configuration::api_key_prefix->{'api_key'} = "BEARER";
176176

177-
my $api = WWW::SwaggerClient::StoreApi->new();
177+
my $api_instance = WWW::SwaggerClient::StoreApi->new();
178178

179179
eval {
180-
my $result = $api->get_inventory_in_object();
180+
my $result = $api_instance->get_inventory_in_object();
181181
print Dumper($result);
182182
};
183183
if ($@) {
@@ -223,11 +223,11 @@ WWW::SwaggerClient::Configuration::api_key->{'test_api_key_query'} = 'YOUR_API_K
223223
# uncomment below to setup prefix (e.g. BEARER) for API key, if needed
224224
#WWW::SwaggerClient::Configuration::api_key_prefix->{'test_api_key_query'} = "BEARER";
225225

226-
my $api = WWW::SwaggerClient::StoreApi->new();
227-
my $order_id = 'order_id_example'; # [string] ID of pet that needs to be fetched
226+
my $api_instance = WWW::SwaggerClient::StoreApi->new();
227+
my $order_id = 'order_id_example'; # string | ID of pet that needs to be fetched
228228

229229
eval {
230-
my $result = $api->get_order_by_id(order_id => $order_id);
230+
my $result = $api_instance->get_order_by_id(order_id => $order_id);
231231
print Dumper($result);
232232
};
233233
if ($@) {
@@ -276,11 +276,11 @@ WWW::SwaggerClient::Configuration::api_key->{'x-test_api_client_secret'} = 'YOUR
276276
# uncomment below to setup prefix (e.g. BEARER) for API key, if needed
277277
#WWW::SwaggerClient::Configuration::api_key_prefix->{'x-test_api_client_secret'} = "BEARER";
278278

279-
my $api = WWW::SwaggerClient::StoreApi->new();
280-
my $body = WWW::SwaggerClient::Object::Order->new(); # [Order] order placed for purchasing the pet
279+
my $api_instance = WWW::SwaggerClient::StoreApi->new();
280+
my $body = WWW::SwaggerClient::Object::Order->new(); # Order | order placed for purchasing the pet
281281

282282
eval {
283-
my $result = $api->place_order(body => $body);
283+
my $result = $api_instance->place_order(body => $body);
284284
print Dumper($result);
285285
};
286286
if ($@) {

0 commit comments

Comments
 (0)