The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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.