main_api_module

Defaults to the first module to import Dancer::Plugin::Swagger.

show_ui

Defaults to "true".

ui_url

Defaults to "/doc".

ui_dir

Defaults to a copy of the Swagger UI code bundled with the Dancer::Plugin::Swagger distribution.

auto_discover_skip

Defauls to "/swagger.json" and, if "show_ui" is "true", all the urls under "ui_url".

validate_response

Defaults to "false".

strict_validation

Defaults to "false".

swagger_path $description, \%args, $route

    swagger_path {
        description => 'Returns info about a judge',
    },
    get '/judge/:judge_name' => sub {
        ...;
    };

Registers a route as a swagger path item in the swagger document.

%args is optional.

The $description is optional as well, and can also be defined as part of the %args.

    # equivalent to the main example
    swagger_path 'Returns info about a judge',
    get '/judge/:judge_name' => sub {
        ...;
    };

If the $description spans many lines, it will be left-trimmed.

    swagger_path q{ 
        Returns info about a judge.

        Some more documentation can go here.

            And this will be seen as a performatted block
            by swagger.
    }, 
    get '/judge/:judge_name' => sub {
        ...;
    };

Supported arguments

method

The HTTP method (GET, POST, etc) for the path item.

Defaults to the route's method.

path

The url for the path item.

Defaults to the route's path.

description

The path item's description.

tags

Optional arrayref of tags assigned to the path.

parameters

List of parameters for the path item. Must be an arrayref or a hashref.

Route parameters are automatically populated. E.g.,

    swagger_path
    get '/judge/:judge_name' => { ... };
    

is equivalent to

    swagger_path {
        parameters => [
            { name => 'judge_name', in => 'path', required => 1, type => 'string' },
        ] 
    },
    get '/judge/:judge_name' => { ... };
    

If the parameters are passed as a hashref, the keys are the names of the parameters, and they will appear in the swagger document following their alphabetical order.

If the parameters are passed as an arrayref, they will appear in the document in the order in which they are passed. Additionally, each parameter can be given as a hashref, or can be a "name => arguments" pair.

In both format, for the key/value pairs, a string value is considered to be the "description" of the parameter.

Finally, if not specified explicitly, the "in" argument of a parameter defaults to "query", and its type to "string".

    parameters => [
        { name => 'bar', in => 'path', required => 1, type => 'string' },
        { name => 'foo', in => 'query', type => 'string', description => 'yadah' },
    ],

    # equivalent arrayref with mixed pairs/non-pairs

    parameters => [
        { name => 'bar', in => 'path', required => 1, type => 'string' },
        foo => { in => 'query', type => 'string', description => 'yadah' },
    ],

    # equivalent hashref format 
    
    parameters => {
        bar => { in => 'path', required => 1, type => 'string' },
        foo => { in => 'query', type => 'string', description => 'yadah' },
    },

    # equivalent, using defaults
    parameters => {
        bar => { in => 'path', required => 1 },
        foo => 'yadah',
    },
    

responses

Possible responses from the path. Must be a hashref.

    swagger_path {
        responses => {
            default => { description => 'The judge information' }
        },
    },
    get '/judge/:judge_name' => { ... };
    

If the key "example" is given (instead of "examples" as defined by the Swagger specs), and the serializer used by the application is Dancer::Serializer::JSON or Dancer::Serializer::YAML, the example will be expanded to have the right content-type key.

    swagger_path {
        responses => {
            default => { example => { fullname => 'Mary Ann Murphy' } }
        },
    },
    get '/judge/:judge_name' => { ... };

    # equivalent to

    swagger_path {
        responses => {
            default => { examples => { 'application/json' => { fullname => 'Mary Ann Murphy' } } }
        },
    },
    get '/judge/:judge_name' => { ... };
    

The special key "template" will not appear in the Swagger doc, but will be used by the "swagger_template" plugin keyword.

swagger_template $code, $args

    swagger_path {
        responses => {
            404 => { template => sub { +{ error => "judge '$_[0]' not found" } }  
        },
    },
    get '/judge/:judge_name' => {  
        my $name = param('judge_name');
        return swagger_template 404, $name unless in_db($name);
        ...;
    };

Calls the template for the $code response, passing it $args. If $code is numerical, also set the response's status to that value.

swagger_auto_discover skip => \@list

Accepts an optional "skip" parameter that takes an arrayref of routes that shouldn't be added to the Swagger document. The routes can be specified as-is, or via regular expressions. If no skip list is given, defaults to the c<auto_discover_skip> configuration value.

    swagger_auto_discover skip => [ '/swagger.json', qr#^/doc/# ];

The information of a route won't be altered if it's already present in the document.

If a route has path parameters, they will be automatically added as such in the "parameters" section.

Routes defined as regexes are skipped, as there is no clean way to automatically make them look nice.

        # will be picked up
    get '/user' => ...;

        # ditto, as '/user/{user_id}'
    get '/user/:user_id => ...;

        # won't be picked up
    get qr#/user/(\d+)# => ...;

Note that routes defined after "swagger_auto_discover" has been called won't be added to the Swagger document. Typically, you'll want "swagger_auto_discover" to be called at the very end of your module. Alternatively, "swagger_auto_discover" can be called more than once safely -- which can be useful if an application creates routes dynamically.

swagger_definition $name => $definition, ...

    swagger_definition 'Judge' => {
        type => 'object',
        required => [ 'fullname' ],
        properties => {
            fullname => { type => 'string' },
            seasons => { type => 'array', items => { type => 'integer' } },
        }
    };

The function returns the reference to the definition that can be then used where schemas are used.

    my $Judge = swagger_definition 'Judge' => { ... };
    # $Judge is now the hashref '{ '$ref' => '#/definitions/Judge' }'
    
    # later on...
    swagger_path {
        responses => {
            default => { schema => $Judge },
        },
    },
    get '/judge/:name' => sub { ... };