mediamath / catalyst-controller-swagger Goto Github PK

Hi,

Our company would like to try this library. But compared to installing from Github, we would rather prefer installing from CPAN. Libraries from CPAN are better known by the Perl world, thus could have less chance to get namespace changing or collision with other libraries in future.

Besides, I see you are having "Swagger" at the top level namespace. I wonder if it could be better to move it into some namespace like Catalyst::Controller::Swagger::Spec?

Thanks!

It's rather a question than an error (maybe missing documentation?). I'm a bloody newbie on Swagger and on integrating swagger into catalyst - therefore bare with me ... ;-)

I tried to run your example within my current catalyst environment:

package MyProject::Controller::TestSwagger;
use base 'Catalyst::Controller::Swagger';
use Swagger qw(add_meta);

__PACKAGE__->config(
  'default'   => 'application/json',
  'stash_key' => 'rest',
  'map'   => {
'text/html'  => [ 'View', 'TT', ],
'text/xml'   => 'XML::Simple',
'application/json'   => 'JSON'
  },
  'swagger' => {
 'api_version'  => '0.0.1',
 'info'  => {
    'title'   => 'test project',
    'description' => 'test description',
 },
   }
);

add_meta {
action => 'test_one',
params => [
  { name => 'start', type => 'integer' }
],
 };

sub test_one_base :Chained('/') :PathPart('test_one') :CaptureArgs(2) {
  my ( $self, $c ) = @_;
}

sub test_one :Chained('test_one_base') :PathPart('foo') :Args(1) :Swagger {
  my ($self, $c) = @_;
  $c->response->body("test_one");
}
# A swagger route can be flagged to be swagger with the :Swagger attribute
sub test_two :Local :Swagger {
  my ($self, $c) = @_;
  $c->response->body('test_two');
}

1;

Doing so everything starts up without errors - and additional pathspecs are provided (/testswagger/api_docs/... , /testswagger/test_two/..., /test_one/*/*/foo/*)

Opening the page http://127.0.0.1:3001/testswagger/api_docsin my browser, I get the error:

Caught exception in BDBInfo2::Controller::TestSwagger->api_docs "A base path must be supplied in the configuration at D:/Usr/programme/Strawberry/perl/site/lib/Swagger/V12.pm line 40."

Any idea what's wrong? Maybe the given example might be expanded to address this ...

Within your Readme.md-example you have following:

# A swagger route can be flagged to be swagger with the :Swagger attribute
sub test_two :Local :Swagger {
  my ($self, $c) = @_;
  $c->response->body('test_two');
}

And later you wrote:""Any additional metadata that would need to be exposed would need to use the Swagger::add_meta function to associate it." (within Section Attribute :Swagger)

But ... I cannot figure out, how to do this.

Could you please give an example, how to add additional metadata (for example description in the example above) - while using the :Swagger-Attribute?

To decrease the barriers to entry to potential contributors to this repository, I would encourage you to enable users, once they have downloaded your code, to build and test your module with standard Perl tools, i.e., a Makefile.PL that will enable one to say:

perl Makefile.PL
make
make test

In other words, you should not implicitly require the use of more advanced, but less widely used, tools such as Dist::Zilla or carton.

Also, please consider reducing your prerequisites for building and testing code. If, for example, Test::More functions will suffice, then require that rather than Test::Most.

Thank you very much.
Jim Keenan