/ 
Mojolicious-Plugin-OpenAPI-0.04
River stage two • 7 direct dependents • 15 total dependents
/ Mojolicious::Plugin::OpenAPI

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