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-Modern-0.010
River stage zero No dependents
2 ++
/ Mojolicious::Plugin::OpenAPI::Modern

NAME

Mojolicious::Plugin::OpenAPI::Modern - Mojolicious plugin providing access to an OpenAPI document and parser

VERSION

version 0.010

SYNOPSIS

  $app->config({
    openapi => {
      document_filename => 'data/openapi.yaml',
      after_response => sub ($c) { ... },
    },
    ...
  });

  $app->plugin('OpenAPI::Modern', $app->config->{openapi});

  # in a controller...
  my $result = $c->openapi->validate_request($c->req);

DESCRIPTION

This Mojolicious plugin makes an OpenAPI::Modern object available to the application.

There are many features to come.

CONFIGURATION OPTIONS

schema

The literal, unblessed Perl data structure containing the OpenAPI document. See "openapi_schema" in OpenAPI::Modern; passed to the OpenAPI::Modern constructor. Only used if "openapi_obj" is not provided.

document_filename

A filename indicating from where to load the OpenAPI document. Supports YAML and json file formats. Only used if "schema" is not provided; also passed to the OpenAPI::Modern constructor as openapi_uri. Only used if "openapi_obj" is not provided.

openapi_obj

An OpenAPI::Modern object to use

after_response

A subref which runs after the response has been finalized, to allow you to perform validation on it. You must not mutate the response here, nor swap it out for a different response, so use this only for telemetry and logging.

  my $after_response = sub ($c) {
    my $result = $c->validate_response;
    if ($result) {
      $c->log->debug('response is valid');
    }
    else {
      # see JSON::Schema::Modern::Result for different output formats
      $c->log->error("response is invalid:\n", $result);
    }
  };

METHODS

register

Instantiates an OpenAPI::Modern object and provides an accessor to it.

HELPERS

These methods are made available on the $c object (the invocant of all controller methods, and therefore other helpers).

openapi

The OpenAPI::Modern object; it holds your OpenAPI specification and is reused between requests.

validate_request

  my $result = $c->openapi->validate_request;

Passes $c->req to "validate_request" in OpenAPI::Modern and returns a JSON::Schema::Modern::Result object.

Note that the matching Mojo::Routes::Route object for this request is not used to find the OpenAPI path-item that corresponds to this request: only information in the request URI itself is used (although some information in the route may be used in future features).

You might want to define an under route action that calls validate_request and short-circuits with an HTTP 400 response on validation failure.

validate_response

  my $result = $c->openapi->validate_response;

Passes $c->res and $c->req to "validate_response" in OpenAPI::Modern and returns a JSON::Schema::Modern::Result object.

As this can only be called in the parts of the dispatch flow where the response has already been rendered and finalized, a hook has been set up for you; you can access it by providing a subref to the "after_response" configuration value:

  $app->config->{openapi}{after_response} //= sub ($c) {
    my $result = $c->validate_response;
    # ... do something with the validation result
  };

Note that the matching Mojo::Routes::Route object for this request is not used to find the OpenAPI path-item that corresponds to this request and response: only information in the request URI itself is used (although some information in the route may be used in future features).

STASH VALUES

This plugin stores all its data under the openapi hashref, e.g.:

  my $operation_id = $c->stash->{openapi}{operation_id};

Keys starting with underscore are for internal use only and should not be relied upon to behave consistently across release versions. Values that may be used by controllers and templates are:

SEE ALSO

SUPPORT

Bugs may be submitted through https://github.com/karenetheridge/Mojolicious-Plugin-OpenAPI-Modern/issues.

I am also usually active on irc, as 'ether' at irc.perl.org and irc.libera.chat.

You can also find me on the JSON Schema Slack server and OpenAPI Slack server, which are also great resources for finding help.

AUTHOR

Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENCE

This software is copyright (c) 2021 by Karen Etheridge.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.