SYNOPSIS
package MyApp;
use Mojo::Base "Mojolicious";
sub startup {
my $app = shift;
$app->plugin(Swagger2 => {url => "data://MyApp/petstore.json"});
}
__DATA__
@@ petstore.json
{
"swagger": "2.0",
"info": {...},
"host": "petstore.swagger.wordnik.com",
"basePath": "/api",
"paths": {
"/pets": {
"get": {...}
}
}
}
DESCRIPTION
Mojolicious::Plugin::Swagger2 is Mojolicious::Plugin that add routes and input/output validation to your Mojolicious application.Have a look at the ``RESOURCES'' for a complete reference to what is possible or look at Swagger2::Guides::Tutorial for an introduction.
RESOURCES
- Swagger2::Guides::Tutorial - Tutorial for this plugin
- Swagger2::Guides::Render - Details about the render process
- Swagger2::Guides::ProtectedApi - Protected API Guide
- Swagger2::Guides::CustomPlaceholder - Custom placeholder for your routes
- Swagger2::Guides::JSONSchemaSupport - Adding json-schema support - EXPERIMENTAL
- Swagger spec <https://github.com/jhthorsen/swagger2/blob/master/t/blog/api.json>
- Application <https://github.com/jhthorsen/swagger2/blob/master/t/blog/lib/Blog.pm>
- Controller <https://github.com/jhthorsen/swagger2/blob/master/t/blog/lib/Blog/Controller/Posts.pm>
- Tests <https://github.com/jhthorsen/swagger2/blob/master/t/authenticate.t>
HOOKS
swagger_route_added
This hook will be DEPRECATED! See <https://github.com/jhthorsen/swagger2/issues/65>.STASH VARIABLES
swagger
The Swagger2 object used to generate the routes is available as "swagger" from stash. Example code:
sub documentation { my ($c, $args, $cb); $c->$cb($c->stash('swagger')->pod->to_string, 200); }
swagger_operation_spec
The Swagger specification for the current operation object <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject> is stored in the ``swagger_operation_spec'' stash variable.
sub list_pets { my ($c, $args, $cb); $c->app->log->info($c->stash("swagger_operation_spec")->{operationId}); ... }
ATTRIBUTES
url
Holds the URL to the swagger specification file.HELPERS
dispatch_to_swagger
$bool = $c->dispatch_to_swagger(\%data);
This helper can be used to handle WebSocket requests with swagger. See Swagger2::Guides::WebSocket for details.
This helper is EXPERIMENTAL.
render_swagger
$c->render_swagger(\%err, \%data, $status);
This method is used to render %data from the controller method. The %err hash will be empty on success, but can contain input/output validation errors. $status is used to set a proper HTTP status code such as 200, 400 or 500.
See also Swagger2::Guides::Render for more information.
METHODS
register
$self->register($app, \%config);
This method is called when this plugin is registered in the Mojolicious application.
%config can contain these parameters:
-
coerce
This argument will be passed on to ``coerce'' in JSON::Validator.
-
ensure_swagger_response
$app->plugin(swagger2 => { ensure_swagger_response => { exception => "Internal server error.", not_found => "Not found.", } });
Adds a before_render hook which will make sure ``exception'' and ``not_found'' responses are in JSON format. There is no need to specify ``exception'' and ``not_found'' if you are happy with the defaults.
-
route
Need to hold a Mojolicious route object. See ``Protected API'' for an example.
This parameter is optional.
-
spec_path
Holds the location for where the specifiation can be served from. The default value is ``/'', relative to ``basePath'' in the specification. Can be disabled by setting this value to empty string.
-
validate
A boolean value (default is true) that will cause your schema to be validated. This plugin will abort loading if the schema include errors
-
swagger
A "Swagger2" object. This can be useful if you want to keep use the specification to other things in your application. Example:
use Swagger2; my $swagger = Swagger2->new->load($url); plugin Swagger2 => {swagger => $swagger2}; app->defaults(swagger_spec => $swagger->api_spec);
Either this parameter or "url" need to be present.
-
url
This will be used to construct a new Swagger2 object. The "url" can be anything that ``load'' in Swagger2 can handle.
Either this parameter or "swagger" need to be present.
COPYRIGHT AND LICENSE
Copyright (C) 2014-2015, Jan Henning ThorsenThis program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.