The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Mojolicious-Plugin-OpenAPI-1.08
River stage two • 7 direct dependents • 14 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 {

    # 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