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:

    * 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".

    * 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
      <https://github.com/jhthorsen/mojolicious-plugin-openapi/compare/webso
      cket>.

    * 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

    * <http://thorsen.pm/perl/programming/2015/07/05/mojolicious-swagger2.ht
      ml>.

    * OpenAPI specification <https://openapis.org/specification>

    * Mojolicious::Plugin::Swagger2.

