The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mojolicious-Plugin-OpenAPI-0.07
River stage two • 6 direct dependents • 12 total dependents
45 ++
/ 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->openapi->valid_input or 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
        }
      }
    }
  }

openapi.valid_input

  $c = $c->openapi->valid_input;

Returns the Mojolicious::Controller object if the input is valid. This helper will also auto render a response. Use "openapi.invalid_input" if this is not the desired behavior.

See "SYNOPSIS" for example usage.

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"),
  });

  • 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.

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