NAME
Mojolicious::Plugin::OpenAPI - OpenAPI / Swagger plugin for Mojolicious
SYNOPSIS
Specification
{
"paths": {
"/pets": {
"get": {
"x-mojo-to": "pet#list",
"summary": "Finds pets in the system",
"responses": {
"200": {
"description": "Pet response",
"schema": { "type": "array", "items": { "$ref": "#/definitions/Pet" } }
},
"default": {
"description": "Unexpected error",
"schema": { "$ref": "http://git.io/vcKD4#" }
}
}
}
}
}The important part in the spec above is "x-mojo-to". The "x-mojo-to" key can either a plain string, object (hash) or an array. The string and hash will be passed directly to "to" in Mojolicious::Routes::Route, while the array ref, will be flattened first.
"x-mojo-to": "pet#list"
$route->to("pet#list");
"x-mojo-to": {"controller": "pet", "action": "list", "foo": 123}
$route->to({controller => "pet", action => "list", foo => 123);
"x-mojo-to": ["pet#list", {"foo": 123}]
$route->to("pet#list", {foo => 123});Application
package Myapp;
use Mojolicious;
sub register {
my $app = shift;
$app->plugin("OpenAPI" => {url => "myapi.json"});
}See "register" for information about what the plugin config can be, in addition to "url".
Controller
package Myapp::Controller::Pet;
sub list {
my $c = shift;
# You might want to introspect the specification for the current route
my $spec = $c->openapi->spec;
unless ($spec->{'x-opening-hour'} == (localtime)[2]) {
return $c->reply->openapi([], 498);
}
# $input will be a hash ref if validated and undef on invalid input
my $input = $c->openapi->input or return;
# $output will be validated by the OpenAPI spec before rendered
my $output = {pets => [{name => "kit-e-cat"}]};
$c->reply->openapi($output, 200);
}The controller input and output will only be validated if the "openapi.input" and "reply.openapi" methods are used.
DESCRIPTION
Mojolicious::Plugin::OpenAPI will replace Mojolicious::Plugin::Swagger2.
This plugin is currently EXPERIMENTAL.
HELPERS
openapi.input
$hash = $c->openapi->input;Returns the data which has been validated by the in OpenAPI specification.
openapi.spec
$hash = $c->openapi->spec;Returns the OpenAPI specification for the current route:
{
"paths": {
"/pets": {
"get": {
// This datastructure
}
}
}
}Note: This might return a JSON pointer in the future.
openapi.validate
# validate request
@errors = $c->openapi->validate;
# validate response
@errors = $c->openapi->validate($output, $http_status);Used to validate input or output data. Request validation is always done by "openapi.input".
reply.openapi
$c->reply->openapi($output, $http_status);
$c->reply->openapi;Will validate $output before passing it on to "render" in Mojolicious::Controller. Calling this helper without any arguments will cause auto-rendering of input errors. See "SYNOPSIS" for example.
METHODS
register
$self->register($app, \%config);Loads the OpenAPI specification, validates it and add routes to $app. It will also set up "HELPERS". %config can have:
{
coerce => 0, # default: 1
log_level => "debug", # default: warn
route => $app->routes->under(...) # not required
url => "path/to/specification.json" # required
}route can be specified in case you want to have a protected API.
See "coerce" in JSON::Validator for possible values that coerce can take.
See "schema" in JSON::Validator for the different url formats that is accepted. Note that relative paths will be relative to "home" in Mojo.
TODO
Add WebSockets support.
Add support for /api.html (human readable format)
Never add support for "x-mojo-around-action", but possibly "before action".
AUTHOR
Jan Henning Thorsen
COPYRIGHT AND LICENSE
Copyright (C) 2016, Jan Henning Thorsen
This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.