NAME Mojolicious::Plugin::OpenAPI - OpenAPI / Swagger plugin for Mojolicious SYNOPSIS use Mojolicious::Lite; # Will be moved under "basePath", resulting in "POST /api/echo" post "/echo" => sub { my $c = shift; return if $c->openapi->invalid_input; return $c->reply->openapi(200 => $c->validation->param("body")); }, "echo"; # Load specification and start web server plugin OpenAPI => {url => "data://main/api.json"}; app->start; __DATA__ @@ api.json { "swagger" : "2.0", "info" : { "version": "0.8", "title" : "Pets" }, "schemes" : [ "http" ], "basePath" : "/api", "paths" : { "/echo" : { "post" : { "x-mojo-name" : "echo", "parameters" : [ { "in": "body", "name": "body", "schema": { "type" : "object" } } ], "responses" : { "200": { "description": "Echo response", "schema": { "type": "object" } } } } } } } DESCRIPTION Mojolicious::Plugin::OpenAPI is Mojolicious::Plugin that add routes and input/output validation to your Mojolicious application based on a OpenAPI (Swagger) specification. Have a look at the "SEE ALSO" for references to more documentation, or jump right to the tutorial. Mojolicious::Plugin::OpenAPI will replace Mojolicious::Plugin::Swagger2. This plugin is currently EXPERIMENTAL. HELPERS openapi.invalid_input @errors = $c->openapi->invalid_input; @errors = $c->openapi->invalid_input({auto_render => 0}); Used to validate a request. @errors holds a list of JSON::Validator::Error objects or empty list on valid input. Setting "auto_render" to a false value will disable the internal auto rendering. This is useful if you want to craft a custom resonse. Validated input parameters will be copied to "Mojolicious::Controller/validation", which again can be extracted by the "name" in the parameters list from the spec. Example: # specification: "parameters": [{"in": "body", "name": "whatever", "schema": {"type": "object"}}], # controller my $body = $c->validation->param("whatever"); openapi.spec $hash = $c->openapi->spec; Returns the OpenAPI specification for the current route. Example: { "paths": { "/pets": { "get": { // This datastructure is returned } } } } reply.openapi $c->reply->openapi($status => $output); Will validate $output before passing it on to "render" in Mojolicious::Controller. Note that $output will be passed on using the format key in stash, which defaults to "json". This also goes for auto-rendering. Example: my $format = $c->stash("format") || "json"; $c->render($format => \%output); $status is a HTTP status code. METHODS register $self->register($app, \%config); Loads the OpenAPI specification, validates it and add routes to $app. It will also set up "HELPERS" and adds a before_render hook for auto-rendering of error documents. %config can have: * coerce See "coerce" in JSON::Validator for possible values that "coerce" can take. Default: 1 * log_level "log_level" is used when logging invalid request/response error messages. Default: "warn". * route "route" can be specified in case you want to have a protected API. Example: $app->plugin(OpenAPI => { route => $app->routes->under("/api")->to("user#auth"), url => $app->home->rel_file("cool.api"), }); * url See "schema" in JSON::Validator for the different "url" formats that is accepted. TODO This plugin is still a big rough on the edges, but I decided to release it on CPAN so people can start playing around with it. * Add WebSockets support . * Add support for /api.html (human readable documentation) * 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. SEE ALSO * Mojolicious::Plugin::OpenAPI::Guides::Tutorial * . * OpenAPI specification * Mojolicious::Plugin::Swagger2.