From 9177b3c8a710764138dbe6a61a34edaf0057062b Mon Sep 17 00:00:00 2001 From: Marco Schumann Date: Tue, 14 Mar 2023 12:55:04 +0100 Subject: [PATCH 1/2] style: Remove trailing whitespaces --- README.md | 12 ++++++------ lib/Catalyst/Controller/Swagger.pm | 26 +++++++++++++------------- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 6b07019..6e2a5ce 100644 --- a/README.md +++ b/README.md @@ -47,9 +47,9 @@ which will contain JSON that is Swagger 1.2 compatible. ## :Swagger Attribute -When this attribute is applied to an action metadata that is implicit to the route will +When this attribute is applied to an action metadata that is implicit to the route will be exposed to the api\_docs route. The data that is exposed include the following: path, method, -and route nickname. Any additional metadata that would need to be exposed would need to use +and route nickname. Any additional metadata that would need to be exposed would need to use the Swagger::add\_meta function to associate it. Here is an example of what the default swagger output looks like: @@ -69,7 +69,7 @@ Here is an example of what the default swagger output looks like: ## api\_docs route This is a route that is exposed that will output a JSON data structure that is Swagger 1.2 -compatible. +compatible. ## Swagger::add\_meta @@ -92,16 +92,16 @@ For further information on Swagger and what it is see: http://www.swagger.io The code for \`catalyst-controller-swagger\` is hosted on GitHub at: https://github.com/mediamath/catalyst-controller-swagger/ - + If you would like to contribute code, documentation, tests, or bugfixes, follow these steps: 1. Fork the project on GitHub. 2. Clone the fork to your local machine. 3. Make your changes and push them back up to your GitHub account. - 4. Send a "pull request" with a brief description of your changes, and a link to a JIRA + 4. Send a "pull request" with a brief description of your changes, and a link to a JIRA ticket if there is one. - + If you are unfamiliar with GitHub, start with their excellent documentation here: diff --git a/lib/Catalyst/Controller/Swagger.pm b/lib/Catalyst/Controller/Swagger.pm index e41d477..84aee1d 100644 --- a/lib/Catalyst/Controller/Swagger.pm +++ b/lib/Catalyst/Controller/Swagger.pm @@ -120,9 +120,9 @@ which will contain JSON that is Swagger 1.2 compatible. =head2 :Swagger Attribute -When this attribute is applied to an action meta data that is implicit to the route will +When this attribute is applied to an action meta data that is implicit to the route will be exposed to the api_docs route. The data that is exposed include the following: path, method, -and route nickname. Any additional meta data that would need to be exposed would need to use +and route nickname. Any additional meta data that would need to be exposed would need to use the Swagger::add_meta function to associate it. Here is an example of what the default swagger output looks like: @@ -142,13 +142,13 @@ Here is an example of what the default swagger output looks like: =head2 api_docs route This is a route that is exposed that will output a JSON data structure that is Swagger 1.2 -compatible. +compatible. =head2 Swagger::add_meta The add_meta function allows a developer to associate other allowed swagger meta data. For example params would specify what sort of parameters a route would accept: - + add_meta { action => 'test_one', # name of route params => [ @@ -167,29 +167,29 @@ For further information on Swagger and what it is see: http://www.swagger.io =head1 CONTRIBUTING The code for `catalyst-controller-swagger` is hosted on GitHub at: - + https://github.com/mediamath/catalyst-controller-swagger/ - + If you would like to contribute code, documentation, tests, or bugfixes, follow these steps: - + 1. Fork the project on GitHub. 2. Clone the fork to your local machine. 3. Make your changes and push them back up to your GitHub account. - 4. Send a "pull request" with a brief description of your changes, and a link to a JIRA + 4. Send a "pull request" with a brief description of your changes, and a link to a JIRA ticket if there is one. - + If you are unfamiliar with GitHub, start with their excellent documentation here: - + https://help.github.com/articles/fork-a-repo =cut =head1 COPYRIGHT & LICENSE - + Copyright 2015, Logan Bell & John Napiorkowski / MediaMath - + This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. - + =cut From e3915260abbc9b05a50b0129930e7b513d20dd37 Mon Sep 17 00:00:00 2001 From: Marco Schumann Date: Tue, 14 Mar 2023 14:25:07 +0100 Subject: [PATCH 2/2] style: Minor POD fixes Also adds a demo config, it took me several minutes to find out howto avoid A base path must be supplied in the configuration --- README.md | 99 ++++++++++++---------- lib/Catalyst/Controller/Swagger.pm | 128 ++++++++++++++++------------- 2 files changed, 127 insertions(+), 100 deletions(-) diff --git a/README.md b/README.md index 6e2a5ce..645bae2 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,57 @@ # NAME - Catalyst::Controller::Swagger + Catalyst::Controller::Swagger # SYNOPSIS - package MyApp::Controller::Root; - use base 'Catalyst::Controller::Swagger'; - use Swagger qw(add_meta); + package MyApp::Controller::Root; + use base 'Catalyst::Controller::Swagger'; + use Swagger qw(add_meta); __PACKAGE__->config( - swagger => { - api_version => '2.2.3', - info => { - title => 'test project', - description => 'test description', - }, - } - }; - - - add_meta { + swagger => { + api_version => '2.2.3', + ## base_path is required + base_path => 'https//my.swagger.host/demo', + info => { + title => 'test project', + description => 'test description', + }, + } + ); + + add_meta { action => 'test_one', params => [ - { name => 'start', type => 'integer' } + { name => 'start', type => 'integer' } ], - }; + }; sub test_one_base :Chained('/') :PathPart('test_one') :CaptureArgs(2) { - my ( $self, $c ) = @_; + my ($self, $c, $arg1, $arg2) = @_; } + # A swagger route can be flagged to be swagger with the :Swagger attribute sub test_one :Chained('test_one_base') :PathPart('foo') :Args(1) :Swagger { - my ($self, $c) = @_; - $c->response->body("test_one"); + my ($self, $c, $arg1) = @_; + $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'); + my ($self, $c) = @_; + $c->response->body('test_two'); } +If the controller has to be configured by a configfile you have to provide a +`swagger` section, here a YAML file: + + --- + ... + Contoller::Root: + swagger: + base_path: https//my.swagger.host/demo + ... + # DESCRIPTION Add swagger metadata to any Catalyst route. This module will expose an "api\_docs" route @@ -54,17 +66,17 @@ the Swagger::add\_meta function to associate it. Here is an example of what the default swagger output looks like: - { - path => '/test_two', - operations => [{ - method => 'GET', - summary => '', - notes => '', - type => '', - nickname => 'GET_/test_two', - summary => '', + { + path => '/test_two', + operations => [{ + method => 'GET', + summary => '', + notes => '', + type => '', + nickname => 'GET_/test_two', + summary => '', }], - } + } ## api\_docs route @@ -76,32 +88,29 @@ compatible. The add\_meta function allows a developer to associate other allowed swagger metadata. For example params would specify what sort of parameters a route would accept: - add_meta { + add_meta { action => 'test_one', # name of route params => [ - { name => 'start', type => 'integer' } + { name => 'start', type => 'integer' } ], - }; + }; # Swagger -For further information on Swagger and what it is see: http://www.swagger.io +For further information on Swagger and what it is see [swagger.io](https://swagger.io). # CONTRIBUTING The code for \`catalyst-controller-swagger\` is hosted on GitHub at: - https://github.com/mediamath/catalyst-controller-swagger/ - + https://github.com/mediamath/catalyst-controller-swagger/ If you would like to contribute code, documentation, tests, or bugfixes, follow these steps: - 1. Fork the project on GitHub. - 2. Clone the fork to your local machine. - 3. Make your changes and push them back up to your GitHub account. - 4. Send a "pull request" with a brief description of your changes, and a link to a JIRA - ticket if there is one. - +1. Fork the project on GitHub. +2. Clone the fork to your local machine. +3. Make your changes and push them back up to your GitHub account. +4. Send a "pull request" with a brief description of your changes, and a link to a JIRA ticket if there is one. If you are unfamiliar with GitHub, start with their excellent documentation here: diff --git a/lib/Catalyst/Controller/Swagger.pm b/lib/Catalyst/Controller/Swagger.pm index 84aee1d..cd406e0 100644 --- a/lib/Catalyst/Controller/Swagger.pm +++ b/lib/Catalyst/Controller/Swagger.pm @@ -72,72 +72,83 @@ sub api_docs : Local { =head1 NAME - Catalyst::Controller::Swagger + Catalyst::Controller::Swagger =head1 SYNOPSIS - package MyApp::Controller::Root; - use base 'Catalyst::Controller::Swagger'; - use Swagger qw(add_meta); + package MyApp::Controller::Root; + use base 'Catalyst::Controller::Swagger'; + use Swagger qw(add_meta); __PACKAGE__->config( - swagger => { - api_version => '2.2.3', - info => { - title => 'test project', - description => 'test description', - }, - } - }; - - - add_meta { + swagger => { + api_version => '2.2.3', + ## base_path is required + base_path => 'https//my.swagger.host/demo', + info => { + title => 'test project', + description => 'test description', + }, + } + ); + + add_meta { action => 'test_one', params => [ - { name => 'start', type => 'integer' } + { name => 'start', type => 'integer' } ], - }; + }; sub test_one_base :Chained('/') :PathPart('test_one') :CaptureArgs(2) { - my ( $self, $c ) = @_; + my ($self, $c, $arg1, $arg2) = @_; } + # A swagger route can be flagged to be swagger with the :Swagger attribute sub test_one :Chained('test_one_base') :PathPart('foo') :Args(1) :Swagger { - my ($self, $c) = @_; - $c->response->body("test_one"); + my ($self, $c, $arg1) = @_; + $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'); + my ($self, $c) = @_; + $c->response->body('test_two'); } +If the controller has to be configured by a configfile you have to provide a +C section, here a YAML file: + + --- + ... + Contoller::Root: + swagger: + base_path: https//my.swagger.host/demo + ... =head1 DESCRIPTION -Add swagger meta data to any Catalyst route. This module will expose an "api_docs" route +Add swagger metadata to any Catalyst route. This module will expose an "api_docs" route which will contain JSON that is Swagger 1.2 compatible. =head2 :Swagger Attribute -When this attribute is applied to an action meta data that is implicit to the route will +When this attribute is applied to an action metadata that is implicit to the route will be exposed to the api_docs route. The data that is exposed include the following: path, method, -and route nickname. Any additional meta data that would need to be exposed would need to use +and route nickname. Any additional metadata that would need to be exposed would need to use the Swagger::add_meta function to associate it. Here is an example of what the default swagger output looks like: - { - path => '/test_two', - operations => [{ - method => 'GET', - summary => '', - notes => '', - type => '', - nickname => 'GET_/test_two', - summary => '', + { + path => '/test_two', + operations => [{ + method => 'GET', + summary => '', + notes => '', + type => '', + nickname => 'GET_/test_two', + summary => '', }], - } + } =head2 api_docs route @@ -146,43 +157,51 @@ compatible. =head2 Swagger::add_meta -The add_meta function allows a developer to associate other allowed swagger meta data. For example +The add_meta function allows a developer to associate other allowed swagger metadata. For example params would specify what sort of parameters a route would accept: - add_meta { + add_meta { action => 'test_one', # name of route params => [ - { name => 'start', type => 'integer' } + { name => 'start', type => 'integer' } ], - }; - -=cut + }; =head1 Swagger -For further information on Swagger and what it is see: http://www.swagger.io - -=cut +For further information on Swagger and what it is see L. =head1 CONTRIBUTING The code for `catalyst-controller-swagger` is hosted on GitHub at: - https://github.com/mediamath/catalyst-controller-swagger/ + https://github.com/mediamath/catalyst-controller-swagger/ If you would like to contribute code, documentation, tests, or bugfixes, follow these steps: - 1. Fork the project on GitHub. - 2. Clone the fork to your local machine. - 3. Make your changes and push them back up to your GitHub account. - 4. Send a "pull request" with a brief description of your changes, and a link to a JIRA - ticket if there is one. +=over -If you are unfamiliar with GitHub, start with their excellent documentation here: +=item 1. - https://help.github.com/articles/fork-a-repo +Fork the project on GitHub. -=cut +=item 2. + +Clone the fork to your local machine. + +=item 3. + +Make your changes and push them back up to your GitHub account. + +=item 4. + +Send a "pull request" with a brief description of your changes, and a link to a JIRA ticket if there is one. + +=back + +If you are unfamiliar with GitHub, start with their excellent documentation here: + + https://help.github.com/articles/fork-a-repo =head1 COPYRIGHT & LICENSE @@ -192,4 +211,3 @@ This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut -