Raisin::Plugin::Swagger - Generates API description in Swagger 2/OpenAPI compatible format
version 0.94
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
This software is copyright (c) 2019 by Artur Khabibullin.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system 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.