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 { # Validate input request or return an error document my $c = shift->openapi->valid_input or return; # Generate some data my $data = {body => $c->validation->param("body")}; # Validate the output response and render it to the user agent # using a custom "openapi" handler. $c->render(openapi => $data); }, "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" } } } } } } } See Mojolicious::Plugin::OpenAPI::Guides::Tutorial for a tutorial on how to write a "full" app with application class and controllers. 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. HELPERS openapi.spec $hash = $c->openapi->spec($json_pointer) $hash = $c->openapi->spec("/info/title") $hash = $c->openapi->spec; Returns the OpenAPI specification. A JSON Pointer can be used to extract a given section of the specification. The default value of $json_pointer will be relative to the current operation. Example: { "paths": { "/pets": { "get": { // This datastructure is returned by default } } } } openapi.validate @errors = $c->openapi->validate; Used to validate a request. @errors holds a list of JSON::Validator::Error objects or empty list on valid input. Note that this helper is only for customization. You probably want "openapi.valid_input" in most cases. 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.valid_input $c = $c->openapi->valid_input; Returns the Mojolicious::Controller object if the input is valid or automatically render an error document if not and return false. See "SYNOPSIS" for example usage. openapi.not_implemented my $response_data = $c->openapi->not_implemented; The response data in the case of an endpoint not yet being implemented. If you wish to override the default you need to override this helper with your own logic: $app->helper( 'openapi.not_implemented' => sub { my $c = shift; ... } ); This helper is EXPERIMENTAL and subject for change. reply.openapi This helper is discourage and might go away. Have a look at "RENDERER" instead. RENDERER This plugin register a new handler called "openapi". The special thing about this handler is that it will validate the data before sending it back to the user agent. Examples: $c->render(json => {foo => 123}); # without validation $c->render(openapi => {foo => 123}); # with validation This handler will also use "renderer" to format the output data. The code below shows the default "renderer" which generates JSON data: $app->plugin( OpenAPI => { renderer => sub { my ($c, $data) = @_; return Mojo::JSON::encode_json($data); } } ); 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: * allow_invalid_ref The OpenAPI specification does not allow "$ref" at every level, but setting this flag to a true value will ignore the $ref check. Note that setting this attribute is discourage. * 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". * renderer See "RENDERER". * 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"), }); * spec_route_name Name of the route that handles the "basePath" part of the specification and serves the specification. Defaults to "x-mojo-name" in the specification at the top level. * url See "schema" in JSON::Validator for the different "url" formats that is accepted. * version_from_class Can be used to overriden "/info/version" in the API specification, from the return value from the "VERSION()" method in "version_from_class". Defaults to the current $app. 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.