loafle/openapi-generator
3
0
Fork 0
forked from loafle/openapi-generator-original
Code Pull Requests Activity

Removed endpoint API class documentation code

Browse Source 
- there is no standard way for a swagger spec to define descriptive
information for an endpoint API
- added markdown as a format to the autodoc script
- added some version information to autogenerated docs
This commit is contained in:
Dave Baird 2015-11-13 19:30:47 +01:00
parent 970c94a4d9
commit 995a1f547f
13 changed files with 438 additions and 223 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
modules/swagger-codegen/src/main/resources/perl/AutoDoc.mustache
View File

@ -28,11 +28,16 @@ sub _printisa {
my $sub = join ', ', $meta->subclasses;
my $dsub = join ', ', $meta->direct_subclasses;
my $app_name = $self->version_info->{app_name};
my $app_version = $self->version_info->{app_version};
my $generated_date = $self->version_info->{generated_date};
my $generator_class = $self->version_info->{generator_class};
$~ = $how eq 'pod' ? 'INHERIT_POD' : 'INHERIT';
write;
my ($rolepkg, $role_reqs);
$~ = $how eq 'pod' ? 'INHERIT_POD' : 'INHERIT';
write;
foreach my $role (@roles) {
$rolepkg = $role->{package} || next; # some are anonymous, or something
next if $rolepkg eq 'WWW::{{moduleName}}::Role::AutoDoc';
@ -58,6 +63,14 @@ $myclass
$dsub
All subclasses: @*
$sub
Target API: @* @*
$app_name, $app_version
Generated on: @*
$generated_date
Generator class: @*
$generator_class
.
format ROLES =
Composes: ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~
@ -74,6 +87,26 @@ $myclass
@*
$myclass
=head1 VERSION
=head2 @* version: @*
$app_name, $app_version
Automatically generated by the Perl Swagger Codegen project:
=over 4
=item Build date: @*
$generated_date
=item Build package: @*
$generator_class
=item Codegen version:
=back
=head1 INHERITANCE
=head2 Base class(es)
@ -90,6 +123,7 @@ $dsub
@*
$sub
=head1 COMPOSITION
@ -171,6 +205,9 @@ sub _printmethod {
$original_pkg = $on;
$doc = $original_pkg->method_documentation->{$delegate_to}->{summary};
}
else {
$doc = $method->documentation;
}
if ($how eq 'narrow') {
$~ = 'METHOD_NARROW';
@ -302,7 +339,7 @@ sub _printattr {
my $from = $attr->associated_class->name || '';
my $reqd = $attr->is_required ? 'yes' : 'no';
my $lazy = $attr->is_lazy ? 'yes' : 'no';
my $has_doc = $attr->has_documentation ? 'yes' : 'no';
my $has_doc = $attr->has_documentation ? 'yes' : 'no'; # *_api attributes will never have doc, but other attributes might have
my $doc = $attr->documentation || '';
my $handles = join ', ', sort @{$attr->handles || []};
$handles ||= '';

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

@ -1,6 +1,16 @@
# NAME
WWW::{{moduleName}}::Role - a Moose role for the Perl Swagger Codegen project
WWW::{{moduleName}}::Role - a Moose role for the {{appName}}
## {{appName}} version: {{appVersion}}
# VERSION
Automatically generated by the Perl Swagger Codegen project:
- Build date: {{generatedDate}}
- Build package: {{generatorClass}}
- Codegen version:
## A note on Moose
@ -185,6 +195,7 @@ output formats are supported:
-n narrow format
-p POD format
-H HTML format
-m Markdown format
-h print this help message
-c your application class

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

@ -10,25 +10,39 @@ use WWW::{{moduleName}}::ApiFactory;
has base_url => ( is => 'ro',
required => 0,
isa => 'Str',
documentation => 'Root of the server that requests are sent to',
);
has api_factory => ( is => 'ro',
isa => 'WWW::{{moduleName}}::ApiFactory',
builder => '_build_af',
lazy => 1,
documentation => 'Builds an instance of the endpoint API class',
);
has tokens => ( is => 'ro',
isa => 'HashRef',
required => 0,
default => sub {{=<% %>=}}{{}}<%={{ }}=%>, # !
default => sub { {} },
documentation => 'The auth tokens required by the application - basic, OAuth and/or API key(s)',
);
has _cfg => ( is => 'ro',
isa => 'Str',
default => 'WWW::{{moduleName}}::Configuration',
);
has version_info => ( is => 'ro',
isa => 'HashRef',
default => sub { {
app_name => '{{appName}}',
app_version => '{{appVersion}}',
generated_date => '{{generatedDate}}',
generator_class => '{{generatorClass}}',
} },
documentation => 'Information about the application version and the codegen codebase version'
);
sub BUILD {
my $self = shift;
@ -66,7 +80,6 @@ sub BUILD {
default => sub {$self->api_factory->get_api($api_name)},
lazy => 1,
handles => \@delegated,
documentation => $api_class->class_documentation->{description}, # not populated yet
) );
}
}
@ -80,7 +93,23 @@ sub _build_af {
=head1 NAME
WWW::{{moduleName}}::Role - a Moose role for the Perl Swagger Codegen project
WWW::{{moduleName}}::Role - a Moose role for the {{appName}}
=head2 {{appName}} version: {{appVersion}}
=head1 VERSION
Automatically generated by the Perl Swagger Codegen project:
=over 4
=item Build date: {{generatedDate}}
=item Build package: {{generatorClass}}
=item Codegen version:
=back
=head2 A note on Moose
@ -268,12 +297,13 @@ output formats are supported:
-n narrow format
-p POD format
-H HTML format
-m Markdown format
-h print this help message
-c your application class
The C<-c> option allows you to load and inspect your own application. A dummy
namespace is used if you don't supply your own class.
=head1 DOCUMENTATION FROM THE SWAGGER SPEC
Additional documentation for each class and method may be provided by the Swagger

5
modules/swagger-codegen/src/main/resources/perl/api.mustache
View File

@ -33,11 +33,6 @@ use WWW::{{moduleName}}::Configuration;
use base "Class::Data::Inheritable";
__PACKAGE__->mk_classdata('method_documentation' => {});
__PACKAGE__->mk_classdata('class_documentation' => {});
__PACKAGE__->class_documentation({description => '', # TODO
class => '{{classname}}',
} );
sub new {
my $class = shift;

14
modules/swagger-codegen/src/main/resources/perl/autodoc.script.mustache
View File

@ -7,7 +7,7 @@ use Moose::Util qw(apply_all_roles);
use Getopt::Std;
my %options=();
getopts("wnphHc:", \%options);
getopts("wnphmHc:", \%options);
help if $options{h};
my $my_app = $options{c} || 'My::App';
@ -28,10 +28,13 @@ else {
package main;
my $opt;
$opt = 'pod' if $options{p};
$opt = 'wide' if $options{w};
$opt = 'narrow' if $options{n};
$opt = 'pod' if $options{p};
$opt = 'pod' if $options{H};
$opt = 'pod' if $options{m};
$opt ||= 'wide';
my $api = $my_app->new;
@ -42,6 +45,12 @@ if ($options{H}) {
$api->autodoc($opt);
close STDOUT or die "Can't close: $!";
}
elsif ($options{m}) {
my $pod2markdown = "pod2markdown --html-encode-chars 1";
open STDOUT, "| $pod2markdown" or die "Can't fork: $!";
$api->autodoc($opt);
close STDOUT or die "Can't close: $!";
}
else {
$api->autodoc($opt);
}
@ -57,6 +66,7 @@ Usage: autodoc [OPTION] [-c My::App::Class]
-n narrow format
-p POD format
-H HTML format
-m Markdown format
-h print this help message
-c your application class

421
samples/client/petstore/perl/README.md
View File

@ -1,208 +1,281 @@
# NAME
WWW::SwaggerClient::Role - a Moose role for the Perl Swagger Codegen project
My::App
## A note on Moose
# VERSION
This role is the only component of the library that uses Moose. See
WWW::SwaggerClient::ApiFactory for non-Moosey usage.
## Swagger Petstore version: 1.0.0
# SYNOPSIS
Automatically generated by the Perl Swagger Codegen project:
The Perl Swagger Codegen project builds a library of Perl modules to interact with
a web service defined by a Swagger specification. See below for how to build the
library.
- Build date: 2015-11-13T18:23:57.025Z
- Build package: class io.swagger.codegen.languages.PerlClientCodegen
- Codegen version:
This module provides an interface to the generated library. All the classes,
objects, and methods (well, not quite \*all\*, see below) are flattened into this
role.
# INHERITANCE
package MyApp;
use Moose;
with 'WWW::SwaggerClient::Role';
package main;
my $api = MyApp->new({ tokens => $tokens });
my $pet = $api->get_pet_by_id(pet_id => $pet_id);
## Base class(es)
## Structure of the library
Moose::Object
The library consists of a set of API classes, one for each endpoint. These APIs
implement the method calls available on each endpoint.
## Direct subclasses
Additionally, there is a set of "object" classes, which represent the objects
returned by and sent to the methods on the endpoints.
## All subclasses
An API factory class is provided, which builds instances of each endpoint API.
# COMPOSITION
This Moose role flattens all the methods from the endpoint APIs onto the consuming
class. It also provides methods to retrieve the endpoint API objects, and the API
factory object, should you need it.
My::App composes the following roles:
For documentation of all these methods, see AUTOMATIC DOCUMENTATION below.
## `WWW::SwaggerClient::Role`
## Configuring authentication
In the normal case, the Swagger spec will describe what parameters are
required and where to put them. You just need to supply the tokens.
my $tokens = {
# basic
username => $username,
password => $password,
# oauth
access_token => $oauth_token,
# keys
$some_key => { token => $token,
prefix => $prefix,
in => $in, # 'head||query',
},
$another => { token => $token,
prefix => $prefix,
in => $in, # 'head||query',
},
...,
};
my $api = MyApp->new({ tokens => $tokens });
Note these are all optional, as are `prefix` and `in`, and depend on the API
you are accessing. Usually `prefix` and `in` will be determined by the code generator from
the spec and you will not need to set them at run time. If not, `in` will
default to 'head' and `prefix` to the empty string.
The tokens will be placed in the `WWW::SwaggerClient::Configuration` namespace
as follows, but you don't need to know about this.
- `$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.
Requires:
# METHODS
## `base_url`
## `add_pet()`
The generated code has the `base_url` already set as a default value. This method
returns (and optionally sets, but only if the API client has not been
created yet) the current value of `base_url`.
Defined in: WWW::SwaggerClient::PetApi
Delegates to: add_pet()
On: WWW::SwaggerClient::PetApi
Via: pet_api()
Doc: Add a new pet to the store
Same as: $self->pet_api->add_pet()
## `create_user()`
Defined in: WWW::SwaggerClient::UserApi
Delegates to: create_user()
On: WWW::SwaggerClient::UserApi
Via: user_api()
Doc: Create user
Same as: $self->user_api->create_user()
## `create_users_with_array_input()`
Defined in: WWW::SwaggerClient::UserApi
Delegates to: create_users_with_array_input()
On: WWW::SwaggerClient::UserApi
Via: user_api()
Doc: Creates list of users with given input array
Same as: $self->user_api->create_users_with_array_input()
## `create_users_with_list_input()`
Defined in: WWW::SwaggerClient::UserApi
Delegates to: create_users_with_list_input()
On: WWW::SwaggerClient::UserApi
Via: user_api()
Doc: Creates list of users with given input array
Same as: $self->user_api->create_users_with_list_input()
## `delete_order()`
Defined in: WWW::SwaggerClient::StoreApi
Delegates to: delete_order()
On: WWW::SwaggerClient::StoreApi
Via: store_api()
Doc: Delete purchase order by ID
Same as: $self->store_api->delete_order()
## `delete_pet()`
Defined in: WWW::SwaggerClient::PetApi
Delegates to: delete_pet()
On: WWW::SwaggerClient::PetApi
Via: pet_api()
Doc: Deletes a pet
Same as: $self->pet_api->delete_pet()
## `delete_user()`
Defined in: WWW::SwaggerClient::UserApi
Delegates to: delete_user()
On: WWW::SwaggerClient::UserApi
Via: user_api()
Doc: Delete user
Same as: $self->user_api->delete_user()
## `find_pets_by_status()`
Defined in: WWW::SwaggerClient::PetApi
Delegates to: find_pets_by_status()
On: WWW::SwaggerClient::PetApi
Via: pet_api()
Doc: Finds Pets by status
Same as: $self->pet_api->find_pets_by_status()
## `find_pets_by_tags()`
Defined in: WWW::SwaggerClient::PetApi
Delegates to: find_pets_by_tags()
On: WWW::SwaggerClient::PetApi
Via: pet_api()
Doc: Finds Pets by tags
Same as: $self->pet_api->find_pets_by_tags()
## `get_inventory()`
Defined in: WWW::SwaggerClient::StoreApi
Delegates to: get_inventory()
On: WWW::SwaggerClient::StoreApi
Via: store_api()
Doc: Returns pet inventories by status
Same as: $self->store_api->get_inventory()
## `get_order_by_id()`
Defined in: WWW::SwaggerClient::StoreApi
Delegates to: get_order_by_id()
On: WWW::SwaggerClient::StoreApi
Via: store_api()
Doc: Find purchase order by ID
Same as: $self->store_api->get_order_by_id()
## `get_pet_by_id()`
Defined in: WWW::SwaggerClient::PetApi
Delegates to: get_pet_by_id()
On: WWW::SwaggerClient::PetApi
Via: pet_api()
Doc: Find pet by ID
Same as: $self->pet_api->get_pet_by_id()
## `get_user_by_name()`
Defined in: WWW::SwaggerClient::UserApi
Delegates to: get_user_by_name()
On: WWW::SwaggerClient::UserApi
Via: user_api()
Doc: Get user by user name
Same as: $self->user_api->get_user_by_name()
## `login_user()`
Defined in: WWW::SwaggerClient::UserApi
Delegates to: login_user()
On: WWW::SwaggerClient::UserApi
Via: user_api()
Doc: Logs user into the system
Same as: $self->user_api->login_user()
## `logout_user()`
Defined in: WWW::SwaggerClient::UserApi
Delegates to: logout_user()
On: WWW::SwaggerClient::UserApi
Via: user_api()
Doc: Logs out current logged in user session
Same as: $self->user_api->logout_user()
## `place_order()`
Defined in: WWW::SwaggerClient::StoreApi
Delegates to: place_order()
On: WWW::SwaggerClient::StoreApi
Via: store_api()
Doc: Place an order for a pet
Same as: $self->store_api->place_order()
## `update_pet()`
Defined in: WWW::SwaggerClient::PetApi
Delegates to: update_pet()
On: WWW::SwaggerClient::PetApi
Via: pet_api()
Doc: Update an existing pet
Same as: $self->pet_api->update_pet()
## `update_pet_with_form()`
Defined in: WWW::SwaggerClient::PetApi
Delegates to: update_pet_with_form()
On: WWW::SwaggerClient::PetApi
Via: pet_api()
Doc: Updates a pet in the store with form data
Same as: $self->pet_api->update_pet_with_form()
## `update_user()`
Defined in: WWW::SwaggerClient::UserApi
Delegates to: update_user()
On: WWW::SwaggerClient::UserApi
Via: user_api()
Doc: Updated user
Same as: $self->user_api->update_user()
## `upload_file()`
Defined in: WWW::SwaggerClient::PetApi
Delegates to: upload_file()
On: WWW::SwaggerClient::PetApi
Via: pet_api()
Doc: uploads an image
Same as: $self->pet_api->upload_file()
# ATTRIBUTES
## `api_factory`
Returns an API factory object. You probably won't need to call this directly.
is: ro
isa: WWW::SwaggerClient::ApiFactory
reqd: no
lazy: yes
doc: Builds an instance of the endpoint API class
handles:
$self->api_factory('Pet'); # returns a WWW::SwaggerClient::PetApi instance
$self->pet_api; # the same
## `base_url`
# MISSING METHODS
is: ro
isa: Str
reqd: no
lazy: no
doc: Root of the server that requests are sent to
handles:
Most of the methods on the API are delegated to individual endpoint API objects
(e.g. Pet API, Store API, User API etc). Where different endpoint APIs use the
same method name (e.g. `new()`), these methods can't be delegated. So you need
to call `$api->pet_api->new()`.
## `pet_api`
In principle, every API is susceptible to the presence of a few, random, undelegatable
method names. In practice, because of the way method names are constructed, it's
unlikely in general that any methods will be undelegatable, except for:
is: ro
isa: WWW::SwaggerClient::PetApi
reqd: no
lazy: yes
doc:
handles: add_pet, delete_pet, find_pets_by_status, find_pets_by_tags,
get_pet_by_id, update_pet, update_pet_with_form, upload_file
new()
class_documentation()
method_documentation()
## `store_api`
To call these methods, you need to get a handle on the relevant object, either
by calling `$api->foo_api` or by retrieving an object, e.g.
`$api->get_pet_by_id(pet_id => $pet_id)`. They are class methods, so
you could also call them on class names.
is: ro
isa: WWW::SwaggerClient::StoreApi
reqd: no
lazy: yes
doc:
handles: delete_order, get_inventory, get_order_by_id, place_order
# BUILDING YOUR LIBRARY
## `tokens`
See the homepage `https://github.com/swagger-api/swagger-codegen` for full details.
But briefly, clone the git repository, build the codegen codebase, set up your build
config file, then run the API build script. You will need git, Java 7 and Apache
maven 3.0.3 or better already installed.
is: ro
isa: HashRef
reqd: no
lazy: no
doc: The auth tokens required by the application - basic, OAuth and/or API key(s)
handles:
The config file should specify the project name for the generated library:
## `user_api`
{"moduleName":"MyProjectName"}
is: ro
isa: WWW::SwaggerClient::UserApi
reqd: no
lazy: yes
doc:
handles: create_user, create_users_with_array_input,
create_users_with_list_input, delete_user, get_user_by_name,
login_user, logout_user, update_user
Your library files will be built under `WWW::MyProjectName`.
## `version_info`
$ git clone https://github.com/swagger-api/swagger-codegen.git
$ cd swagger-codegen
$ mvn package
$ java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
-i [URL or file path to JSON swagger API spec] \
-l perl \
-c /path/to/config/file.json \
-o /path/to/output/folder
Bang, all done. Run the `autodoc` script in the `bin` directory to see the API
you just built.
# AUTOMATIC DOCUMENTATION
You can print out a summary of the generated API by running the included
`autodoc` script in the `bin` directory of your generated library. A few
output formats are supported:
Usage: autodoc [OPTION]
-w wide format (default)
-n narrow format
-p POD format
-H HTML format
-h print this help message
-c your application class
The `-c` option allows you to load and inspect your own application. A dummy
namespace is used if you don't supply your own class.
# DOCUMENTATION FROM THE SWAGGER SPEC
Additional documentation for each class and method may be provided by the Swagger
spec. If so, this is available via the `class_documentation()` and
`method_documentation()` methods on each generated API and class:
my $cdoc = $api->pet_api->class_documentation;
my $cmdoc = $api->pet_api->method_documentation->{$method_name};
my $odoc = $api->get_pet_by_id->(pet_id => $pet_id)->class_documentation;
my $omdoc = $api->get_pet_by_id->(pet_id => $pet_id)->method_documentation->{method_name};
Each of these calls returns a hashref with various useful pieces of information.
is: ro
isa: HashRef
reqd: no
lazy: no
doc: Information about the application version and the codegen codebase version
handles:

14
samples/client/petstore/perl/bin/autodoc
View File

@ -7,7 +7,7 @@ use Moose::Util qw(apply_all_roles);
use Getopt::Std;
my %options=();
getopts("wnphHc:", \%options);
getopts("wnphmHc:", \%options);
help if $options{h};
my $my_app = $options{c} || 'My::App';
@ -28,10 +28,13 @@ else {
package main;
my $opt;
$opt = 'pod' if $options{p};
$opt = 'wide' if $options{w};
$opt = 'narrow' if $options{n};
$opt = 'pod' if $options{p};
$opt = 'pod' if $options{H};
$opt = 'pod' if $options{m};
$opt ||= 'wide';
my $api = $my_app->new;
@ -42,6 +45,12 @@ if ($options{H}) {
$api->autodoc($opt);
close STDOUT or die "Can't close: $!";
}
elsif ($options{m}) {
my $pod2markdown = "pod2markdown --html-encode-chars 1";
open STDOUT, "| $pod2markdown" or die "Can't fork: $!";
$api->autodoc($opt);
close STDOUT or die "Can't close: $!";
}
else {
$api->autodoc($opt);
}
@ -57,6 +66,7 @@ Usage: autodoc [OPTION] [-c My::App::Class]
-n narrow format
-p POD format
-H HTML format
-m Markdown format
-h print this help message
-c your application class

5
samples/client/petstore/perl/lib/WWW/SwaggerClient/PetApi.pm
View File

@ -33,11 +33,6 @@ use WWW::SwaggerClient::Configuration;
use base "Class::Data::Inheritable";
__PACKAGE__->mk_classdata('method_documentation' => {});
__PACKAGE__->mk_classdata('class_documentation' => {});
__PACKAGE__->class_documentation({description => '', # TODO
class => 'PetApi',
} );
sub new {
my $class = shift;

40
samples/client/petstore/perl/lib/WWW/SwaggerClient/Role.pm
View File

@ -10,25 +10,39 @@ use WWW::SwaggerClient::ApiFactory;
has base_url => ( is => 'ro',
required => 0,
isa => 'Str',
documentation => 'Root of the server that requests are sent to',
);
has api_factory => ( is => 'ro',
isa => 'WWW::SwaggerClient::ApiFactory',
builder => '_build_af',
lazy => 1,
documentation => 'Builds an instance of the endpoint API class',
);
has tokens => ( is => 'ro',
isa => 'HashRef',
required => 0,
default => sub {{}}, # !
default => sub { {} },
documentation => 'The auth tokens required by the application - basic, OAuth and/or API key(s)',
);
has _cfg => ( is => 'ro',
isa => 'Str',
default => 'WWW::SwaggerClient::Configuration',
);
has version_info => ( is => 'ro',
isa => 'HashRef',
default => sub { {
app_name => 'Swagger Petstore',
app_version => '1.0.0',
generated_date => '2015-11-13T18:23:57.025Z',
generator_class => 'class io.swagger.codegen.languages.PerlClientCodegen',
} },
documentation => 'Information about the application version and the codegen codebase version'
);
sub BUILD {
my $self = shift;
@ -66,7 +80,6 @@ sub BUILD {
default => sub {$self->api_factory->get_api($api_name)},
lazy => 1,
handles => \@delegated,
documentation => $api_class->class_documentation->{description}, # not populated yet
) );
}
}
@ -80,7 +93,23 @@ sub _build_af {
=head1 NAME
WWW::SwaggerClient::Role - a Moose role for the Perl Swagger Codegen project
WWW::SwaggerClient::Role - a Moose role for the Swagger Petstore
=head2 Swagger Petstore version: 1.0.0
=head1 VERSION
Automatically generated by the Perl Swagger Codegen project:
=over 4
=item Build date: 2015-11-13T18:23:57.025Z
=item Build package: class io.swagger.codegen.languages.PerlClientCodegen
=item Codegen version:
=back
=head2 A note on Moose
@ -268,12 +297,13 @@ output formats are supported:
-n narrow format
-p POD format
-H HTML format
-m Markdown format
-h print this help message
-c your application class
The C<-c> option allows you to load and inspect your own application. A dummy
namespace is used if you don't supply your own class.
=head1 DOCUMENTATION FROM THE SWAGGER SPEC
Additional documentation for each class and method may be provided by the Swagger

45
samples/client/petstore/perl/lib/WWW/SwaggerClient/Role/AutoDoc.pm
View File

@ -28,11 +28,16 @@ sub _printisa {
my $sub = join ', ', $meta->subclasses;
my $dsub = join ', ', $meta->direct_subclasses;
my $app_name = $self->version_info->{app_name};
my $app_version = $self->version_info->{app_version};
my $generated_date = $self->version_info->{generated_date};
my $generator_class = $self->version_info->{generator_class};
$~ = $how eq 'pod' ? 'INHERIT_POD' : 'INHERIT';
write;
my ($rolepkg, $role_reqs);
$~ = $how eq 'pod' ? 'INHERIT_POD' : 'INHERIT';
write;
foreach my $role (@roles) {
$rolepkg = $role->{package} || next; # some are anonymous, or something
next if $rolepkg eq 'WWW::SwaggerClient::Role::AutoDoc';
@ -58,6 +63,14 @@ $myclass
$dsub
All subclasses: @*
$sub
Target API: @* @*
$app_name, $app_version
Generated on: @*
$generated_date
Generator class: @*
$generator_class
.
format ROLES =
Composes: ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~
@ -74,6 +87,26 @@ $myclass
@*
$myclass
=head1 VERSION
=head2 @* version: @*
$app_name, $app_version
Automatically generated by the Perl Swagger Codegen project:
=over 4
=item Build date: @*
$generated_date
=item Build package: @*
$generator_class
=item Codegen version:
=back
=head1 INHERITANCE
=head2 Base class(es)
@ -90,6 +123,7 @@ $dsub
@*
$sub
=head1 COMPOSITION
@ -171,6 +205,9 @@ sub _printmethod {
$original_pkg = $on;
$doc = $original_pkg->method_documentation->{$delegate_to}->{summary};
}
else {
$doc = $method->documentation;
}
if ($how eq 'narrow') {
$~ = 'METHOD_NARROW';
@ -302,7 +339,7 @@ sub _printattr {
my $from = $attr->associated_class->name || '';
my $reqd = $attr->is_required ? 'yes' : 'no';
my $lazy = $attr->is_lazy ? 'yes' : 'no';
my $has_doc = $attr->has_documentation ? 'yes' : 'no';
my $has_doc = $attr->has_documentation ? 'yes' : 'no'; # *_api attributes will never have doc, but other attributes might have
my $doc = $attr->documentation || '';
my $handles = join ', ', sort @{$attr->handles || []};
$handles ||= '';

5
samples/client/petstore/perl/lib/WWW/SwaggerClient/StoreApi.pm
View File

@ -33,11 +33,6 @@ use WWW::SwaggerClient::Configuration;
use base "Class::Data::Inheritable";
__PACKAGE__->mk_classdata('method_documentation' => {});
__PACKAGE__->mk_classdata('class_documentation' => {});
__PACKAGE__->class_documentation({description => '', # TODO
class => 'StoreApi',
} );
sub new {
my $class = shift;

5
samples/client/petstore/perl/lib/WWW/SwaggerClient/UserApi.pm
View File

@ -33,11 +33,6 @@ use WWW::SwaggerClient::Configuration;
use base "Class::Data::Inheritable";
__PACKAGE__->mk_classdata('method_documentation' => {});
__PACKAGE__->mk_classdata('class_documentation' => {});
__PACKAGE__->class_documentation({description => '', # TODO
class => 'UserApi',
} );
sub new {
my $class = shift;

9
samples/client/petstore/perl/t/04_role.t
View File

@ -1,4 +1,4 @@
use Test::More tests => 38;
use Test::More tests => 37;
use Test::Exception;
use Test::Warnings 'warnings';
use Test::Deep;
@ -15,8 +15,8 @@ SKIP: {
sub auth_setup_handler {}
";
skip 'Moose not installed', 38 if $@;
# die $@ if $@;
skip 'Moose not installed', 37 if $@;
my $api = MyApp->new;
@ -48,9 +48,6 @@ is $get_pet->tags->[0]->id, '11', 'stored and retrieved: got the proper tag id';
# documentation tests
# API class docs
is $api->pet_api->class_documentation->{description}, '', 'got correct Pet API description'; # right now it's blank
# API method docs
is_deeply( [sort keys %{$api->pet_api->method_documentation}],
[ 'add_pet', 'delete_pet', 'find_pets_by_status', 'find_pets_by_tags', 'get_pet_by_id', 'update_pet', 'update_pet_with_form', 'upload_file'],