SYNOPSIS
package MyApp;
use Dancer;
use Dancer::Plugin::Swagger;
our $VERSION = "0.1";
get '/choreograph/:name' => sub { ... };
1;
DESCRIPTION
This plugin provides tools to create and access a Swagger
specification file for a Dancer REST web service.
Overview of Dancer::Plugin::Swagger's features:
Can create a /swagger.json REST specification file.
Can auto-discover routes and add them to the swagger file.
Can provide a Swagger UI version of the swagger documentation.
CONFIGURATION
plugins:
Swagger:
main_api_module: MyApp
show_ui: 1
ui_url: /doc
ui_dir: /path/to/files
auto_discover_skip:
- /swagger.json
- qr#^/doc/#
main_api_module
If not provided explicitly, the Swagger document's title and version
will be set to the abstract and version of this module.
Defaults to the first module to import Dancer::Plugin::Swagger.
show_ui
If true, a route will be created for the Swagger UI (see
http://swagger.io/swagger-ui/).
Defaults to true.
ui_url
Path of the swagger ui route. Will also be the prefix for all the
CSS/JS dependencies of the page.
Defaults to /doc.
ui_dir
Filesystem path to the directory holding the assets for the Swagger UI
page.
Defaults to a copy of the Swagger UI code bundled with the
Dancer::Plugin::Swagger distribution.
auto_discover_skip
List of urls that should not be added to the Swagger document by
swagger_auto_discover. If an url begins with qr, it will be compiled as
a regular expression.
Defauls to /swagger.json and, if show_ui is true, all the urls under
ui_url.
PLUGIN KEYWORDS
swagger_path \%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.
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.
parameters
List of parameters for the path item. Must be an arrayref.
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' => { ... };
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
Populates the Swagger document with information of all the routes of
the application.
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 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, ...
Adds a schema (or more) to the definition section of the Swagger
document.
swagger_definition 'Judge' => {
type => 'object',
required => [ 'fullname' ],
properties => {
fullname => { type => 'string' },
seasons => { type => 'array', items => { type => 'integer' } },
}
};
EXAMPLES
See the examples/ directory of the distribution for a working example.
SEE ALSO
http://swagger.io/|Swagger