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

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

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

    * Mojolicious::Plugin::Swagger2.

