NAME
Raisin::Plugin::Swagger - Generates API description in Swagger 2/OpenAPI compatible format.
SYNOPSIS
plugin 'Swagger';DESCRIPTION
Generates an API description of application.
SPECIFICATION
Compatible with Swagger/OpenAPI Spec 2.0.
CORS
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.
SECURITY
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/];Limitations
Raisin doesn't support per operation security.
Raisin doesn't support oauth2, only basic and api_key are supported.
Example Application
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;FUNCTIONS
swagger_setup
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/',
},
);swagger_security
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.
AUTHOR
Artur Khabibullin - rtkh <at> cpan.org
LICENSE
This module and all the modules in this package are governed by the same license as Perl itself.