Raisin::Plugin::Swagger - Generates API description in Swagger 2/OpenAPI compatible format.
plugin 'Swagger';
Generates an API description of application.
Compatible with Swagger/OpenAPI Spec 2.0.
To enable Cross-Origin HTTP Requests you should enable a Plack::Middleware::CrossOrigin middleware with all the parameters you need (like origins, methods, headers, etc.).
middleware 'CrossOrigin', origins => '*', methods => [qw/DELETE GET HEAD OPTIONS PATCH POST PUT/], headers => [qw/accept authorization content-type api_key_token/];
Alternatively you can set CORS headers in a before hook.
Raisin has a limited support of OpenAPI security objects. To make it generate security objects configure it in the way it described below.
Add a api_key security via stoken header.
swagger_security(name => 'stoken', in => 'header', type => 'api_key');
Add the header name to "CORS" in Raisin::Plugin::Swagger headers if you use api_key.
middleware 'CrossOrigin', origins => '*', methods => [qw/DELETE GET HEAD OPTIONS PATCH POST PUT/], headers => [qw/stoken accept authorization content-type/];
Raisin doesn't support per operation security.
Raisin doesn't support oauth2, only basic and api_key are supported.
Example of a secured application.
use strict; use warnings; middleware '+MyAuthMiddleware'; middleware 'CrossOrigin', origins => '*', methods => [qw/DELETE GET HEAD OPTIONS PATCH POST PUT/], headers => [qw/stoken accept authorization content-type/]; plugin 'Swagger'; swagger_security(name => 'stoken', in => 'header', type => 'api_key'); get sub { { data => 'ok' } }; run;
Example of a middleware used in the application.
package Auth; use strict; use warnings; use parent 'Plack::Middleware'; use Plack::Request; sub call { my ($self, $env) = @_; my $req = Plack::Request->new($env); if (($req->header('stoken') // '') eq 'secret' || $req->path eq '/swagger.json') { $self->app->($env); } else { [403, [], ['forbidden']]; } } 1;
Configures base OpenAPI parameters, be aware they aren't validating and passing to the specification as is.
Properly configured section has following attributes: title, description, terms_service, contact and license.
Contact has name, url, email.
License has name and url.
swagger_setup( title => 'BatAPI', description => 'Simple BatAPI.', contact => { name => 'Bruce Wayne', url => 'http://wayne.enterprises', email => 'bruce@batman.com', }, license => { name => 'Batman license', url => 'http://wayne.enterprises/licenses/', }, );
Configures OpenAPI security options.
Allowed types are basic, api_key and oauth2.
For more information please check OpenAPI specification and "SECURITY" in Raisin::Plugin::Swagger.
Artur Khabibullin - rtkh <at> cpan.org
This module and all the modules in this package are governed by the same license as Perl itself.
To install Raisin, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Raisin
CPAN shell
perl -MCPAN -e shell install Raisin
For more information on module installation, please visit the detailed CPAN module installation guide.