The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

 / 
Raisin-0.94
River stage one • 1 direct dependent • 1 total dependent
/ Raisin::Plugin::Swagger

NAME

Raisin::Plugin::Swagger - Generates API description in Swagger 2/OpenAPI compatible format

VERSION

version 0.94

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

COPYRIGHT AND LICENSE

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.