.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mojolicious::Plugin::OpenAPI 3pm"
.TH Mojolicious::Plugin::OpenAPI 3pm "2023-02-21" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mojolicious::Plugin::OpenAPI \- OpenAPI / Swagger plugin for Mojolicious
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  # It is recommended to use Mojolicious::Plugin::OpenAPI with a "full app".
\&  # See the links after this example for more information.
\&  use Mojolicious::Lite;
\&
\&  # Because the route name "echo" matches the "x\-mojo\-name", this route
\&  # 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\->req\->json};
\&
\&    # 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:///swagger.yaml"};
\&  app\->start;
\&
\&  _\|_DATA_\|_
\&  @@ swagger.yaml
\&  swagger: "2.0"
\&  info: { version: "0.8", title: "Echo Service" }
\&  schemes: ["https"]
\&  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" }
.Ve
.PP
See Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 or
Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv3 for more in depth
information about how to use Mojolicious::Plugin::OpenAPI with a \*(L"full app\*(R".
Even with a \*(L"lite app\*(R" it can be very useful to read those guides.
.PP
Looking at the documentation for
\&\*(L"x\-mojo-to\*(R" in Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 can be especially
useful. (The logic is the same for OpenAPIv2 and OpenAPIv3)
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mojolicious::Plugin::OpenAPI is Mojolicious::Plugin that add routes and
input/output validation to your Mojolicious application based on a OpenAPI
(Swagger) specification. This plugin supports both version 2.0 and
3.x, though 3.x \fImight\fR have some missing features.
.PP
Have a look at the \*(L"\s-1SEE ALSO\*(R"\s0 for references to plugins and other useful
documentation.
.PP
Please report in issues <https://github.com/jhthorsen/json-validator/issues>
or open pull requests to enhance the 3.0 support.
.SH "HELPERS"
.IX Header "HELPERS"
.SS "openapi.spec"
.IX Subsection "openapi.spec"
.Vb 3
\&  $hash = $c\->openapi\->spec($json_pointer)
\&  $hash = $c\->openapi\->spec("/info/title")
\&  $hash = $c\->openapi\->spec;
.Ve
.PP
Returns the OpenAPI specification. A \s-1JSON\s0 Pointer can be used to extract a
given section of the specification. The default value of \f(CW$json_pointer\fR will
be relative to the current operation. Example:
.PP
.Vb 9
\&  {
\&    "paths": {
\&      "/pets": {
\&        "get": {
\&          // This datastructure is returned by default
\&        }
\&      }
\&    }
\&  }
.Ve
.SS "openapi.validate"
.IX Subsection "openapi.validate"
.Vb 1
\&  @errors = $c\->openapi\->validate;
.Ve
.PP
Used to validate a request. \f(CW@errors\fR holds a list of
JSON::Validator::Error objects or empty list on valid input.
.PP
Note that this helper is only for customization. You probably want
\&\*(L"openapi.valid_input\*(R" in most cases.
.SS "openapi.valid_input"
.IX Subsection "openapi.valid_input"
.Vb 1
\&  $c = $c\->openapi\->valid_input;
.Ve
.PP
Returns the Mojolicious::Controller object if the input is valid or
automatically render an error document if not and return false. See
\&\*(L"\s-1SYNOPSIS\*(R"\s0 for example usage.
.SH "HOOKS"
.IX Header "HOOKS"
Mojolicious::Plugin::OpenAPI will emit the following hooks on the
application object.
.SS "openapi_routes_added"
.IX Subsection "openapi_routes_added"
Emitted after all routes have been added by this plugin.
.PP
.Vb 2
\&  $app\->hook(openapi_routes_added => sub {
\&    my ($openapi, $routes) = @_;
\&
\&    for my $route (@$routes) {
\&      ...
\&    }
\&  });
.Ve
.PP
This hook is \s-1EXPERIMENTAL\s0 and subject for change.
.SH "RENDERER"
.IX Header "RENDERER"
This plugin register a new handler called \f(CW\*(C`openapi\*(C'\fR. The special thing about
this handler is that it will validate the data before sending it back to the
user agent. Examples:
.PP
.Vb 2
\&  $c\->render(json => {foo => 123});    # without validation
\&  $c\->render(openapi => {foo => 123}); # with validation
.Ve
.PP
This handler will also use \*(L"renderer\*(R" to format the output data. The code
below shows the default \*(L"renderer\*(R" which generates \s-1JSON\s0 data:
.PP
.Vb 8
\&  $app\->plugin(
\&    OpenAPI => {
\&      renderer => sub {
\&        my ($c, $data) = @_;
\&        return Mojo::JSON::encode_json($data);
\&      }
\&    }
\&  );
.Ve
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "route"
.IX Subsection "route"
.Vb 1
\&  $route = $openapi\->route;
.Ve
.PP
The parent Mojolicious::Routes::Route object for all the OpenAPI endpoints.
.SS "validator"
.IX Subsection "validator"
.Vb 1
\&  $jv = $openapi\->validator;
.Ve
.PP
Holds either a JSON::Validator::Schema::OpenAPIv2 or a
JSON::Validator::Schema::OpenAPIv3 object.
.SH "METHODS"
.IX Header "METHODS"
.SS "register"
.IX Subsection "register"
.Vb 2
\&  $openapi = $openapi\->register($app, \e%config);
\&  $openapi = $app\->plugin(OpenAPI => \e%config);
.Ve
.PP
Loads the OpenAPI specification, validates it and add routes to
\&\f(CW$app\fR. It will also set up \*(L"\s-1HELPERS\*(R"\s0 and adds a
before_render hook for auto-rendering of error
documents. The return value is the object instance, which allow you to access
the \*(L"\s-1ATTRIBUTES\*(R"\s0 after you load the plugin.
.PP
\&\f(CW%config\fR can have:
.PP
\fIcoerce\fR
.IX Subsection "coerce"
.PP
See \*(L"coerce\*(R" in JSON::Validator for possible values that \f(CW\*(C`coerce\*(C'\fR can take.
.PP
Default: booleans,numbers,strings
.PP
The default value will include \*(L"defaults\*(R" in the future, once that is stable enough.
.PP
\fIdefault_response\fR
.IX Subsection "default_response"
.PP
Instructions for
\&\*(L"add_default_response_schema\*(R" in JSON::Validator::Schema::OpenAPIv2. (Also used
for OpenAPIv3)
.PP
\fIformat\fR
.IX Subsection "format"
.PP
Set this to a default list of file extensions that your \s-1API\s0 accepts. This value
can be overwritten by
\&\*(L"x\-mojo-to\*(R" in Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2.
.PP
This config parameter is \s-1EXPERIMENTAL\s0 and subject for change.
.PP
\fIlog_level\fR
.IX Subsection "log_level"
.PP
\&\f(CW\*(C`log_level\*(C'\fR is used when logging invalid request/response error messages.
.PP
Default: \*(L"warn\*(R".
.PP
\fIop_spec_to_route\fR
.IX Subsection "op_spec_to_route"
.PP
\&\f(CW\*(C`op_spec_to_route\*(C'\fR can be provided if you want to add route definitions
without using \*(L"x\-mojo-to\*(R". Example:
.PP
.Vb 2
\&  $app\->plugin(OpenAPI => {op_spec_to_route => sub {
\&    my ($plugin, $op_spec, $route) = @_;
\&
\&    # Here are two ways to customize where to dispatch the request
\&    $route\->to(cb => sub { shift\->render(openapi => ...) });
\&    $route\->to(ucfirst "$op_spec\->{operationId}#handle_request");
\&  }});
.Ve
.PP
This feature is \s-1EXPERIMENTAL\s0 and might be altered and/or removed.
.PP
\fIplugins\fR
.IX Subsection "plugins"
.PP
A list of OpenAPI classes to extend the functionality. Default is:
Mojolicious::Plugin::OpenAPI::Cors,
Mojolicious::Plugin::OpenAPI::SpecRenderer and
Mojolicious::Plugin::OpenAPI::Security.
.PP
.Vb 1
\&  $app\->plugin(OpenAPI => {plugins => [qw(+Cors +SpecRenderer +Security)]});
.Ve
.PP
You can load your own plugins by doing:
.PP
.Vb 1
\&  $app\->plugin(OpenAPI => {plugins => [qw(+SpecRenderer My::Cool::OpenAPI::Plugin)]});
.Ve
.PP
\fIrenderer\fR
.IX Subsection "renderer"
.PP
See \*(L"\s-1RENDERER\*(R"\s0.
.PP
\fIroute\fR
.IX Subsection "route"
.PP
\&\f(CW\*(C`route\*(C'\fR can be specified in case you want to have a protected \s-1API.\s0 Example:
.PP
.Vb 4
\&  $app\->plugin(OpenAPI => {
\&    route => $app\->routes\->under("/api")\->to("user#auth"),
\&    url   => $app\->home\->rel_file("cool.api"),
\&  });
.Ve
.PP
\fIskip_validating_specification\fR
.IX Subsection "skip_validating_specification"
.PP
Used to prevent calling \*(L"errors\*(R" in JSON::Validator::Schema::OpenAPIv2 for the
specification.
.PP
\fIspec_route_name\fR
.IX Subsection "spec_route_name"
.PP
Name of the route that handles the \*(L"basePath\*(R" part of the specification and
serves the specification. Defaults to \*(L"x\-mojo-name\*(R" in the specification at
the top level.
.PP
\fIspec, url\fR
.IX Subsection "spec, url"
.PP
See \*(L"schema\*(R" in JSON::Validator for the different \f(CW\*(C`url\*(C'\fR formats that is
accepted.
.PP
\&\f(CW\*(C`spec\*(C'\fR is an alias for \*(L"url\*(R", which might make more sense if your
specification is written in perl, instead of \s-1JSON\s0 or \s-1YAML.\s0
.PP
Here are some common uses:
.PP
.Vb 4
\&  $app\->plugin(OpenAPI => {url  => $app\->home\->rel_file(\*(Aqopenapi.yaml\*(Aq));
\&  $app\->plugin(OpenAPI => {url  => \*(Aqhttps://example.com/swagger.json\*(Aq});
\&  $app\->plugin(OpenAPI => {spec => JSON::Validator::Schema::OpenAPIv3\->new(...)});
\&  $app\->plugin(OpenAPI => {spec => {swagger => "2.0", paths => {...}, ...}});
.Ve
.PP
\fIversion_from_class\fR
.IX Subsection "version_from_class"
.PP
Can be used to overridden \f(CW\*(C`/info/version\*(C'\fR in the \s-1API\s0 specification, from the
return value from the \f(CW\*(C`VERSION()\*(C'\fR method in \f(CW\*(C`version_from_class\*(C'\fR.
.PP
Defaults to the current \f(CW$app\fR. This can be disabled by setting the
\&\*(L"version_from_class\*(R" to zero (0).
.SH "AUTHORS"
.IX Header "AUTHORS"
.SS "Project Founder"
.IX Subsection "Project Founder"
Jan Henning Thorsen \- \f(CW\*(C`jhthorsen@cpan.org\*(C'\fR
.SS "Contributors"
.IX Subsection "Contributors"
.IP "\(bu" 2
Bernhard Graf <augensalat@gmail.com>
.IP "\(bu" 2
Doug Bell <doug@preaction.me>
.IP "\(bu" 2
Ed J <mohawk2@users.noreply.github.com>
.IP "\(bu" 2
Henrik Andersen <hem@fibia.dk>
.IP "\(bu" 2
Henrik Andersen <hem@hamster.dk>
.IP "\(bu" 2
Ilya Rassadin <elcamlost@gmail.com>
.IP "\(bu" 2
Jan Henning Thorsen <jan.henning@thorsen.pm>
.IP "\(bu" 2
Jan Henning Thorsen <jhthorsen@cpan.org>
.IP "\(bu" 2
Ji-Hyeon Gim <potatogim@gluesys.com>
.IP "\(bu" 2
Joel Berger <joel.a.berger@gmail.com>
.IP "\(bu" 2
Krasimir Berov <k.berov@gmail.com>
.IP "\(bu" 2
Lars Thegler <lth@fibia.dk>
.IP "\(bu" 2
Lee Johnson <lee@givengain.ch>
.IP "\(bu" 2
Linn-Hege Kristensen <linn\-hege@stix.no>
.IP "\(bu" 2
Manuel <manuel@mausz.at>
.IP "\(bu" 2
Martin Renvoize <martin.renvoize@ptfs\-europe.com>
.IP "\(bu" 2
Mohammad S Anwar <mohammad.anwar@yahoo.com>
.IP "\(bu" 2
Nick Morrott <knowledgejunkie@gmail.com>
.IP "\(bu" 2
Renee <reb@perl\-services.de>
.IP "\(bu" 2
Roy Storey <kiwiroy@users.noreply.github.com>
.IP "\(bu" 2
SebMourlhou <35918953+SebMourlhou@users.noreply.github.com>
.IP "\(bu" 2
SebMourlhou <sebastien.mourlhou@justice.ge.ch>
.IP "\(bu" 2
SebMourlhou <sebmourlhou@yahoo.fr>
.IP "\(bu" 2
Søren Lund <sl@keycore.dk>
.IP "\(bu" 2
Stephan Hradek <github@hradek.net>
.IP "\(bu" 2
Stephan Hradek <stephan.hradek@eco.de>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) Jan Henning Thorsen
.PP
This program is free software, you can redistribute it and/or modify it under
the terms of the Artistic License version 2.0.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 2
Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2
.Sp
Guide for how to use this plugin with OpenAPI version 2.0 spec.
.IP "\(bu" 2
Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv3
.Sp
Guide for how to use this plugin with OpenAPI version 3.0 spec.
.IP "\(bu" 2
Mojolicious::Plugin::OpenAPI::Cors
.Sp
Plugin to add Cross-Origin Resource Sharing (\s-1CORS\s0).
.IP "\(bu" 2
Mojolicious::Plugin::OpenAPI::Security
.Sp
Plugin for handling security definitions in your schema.
.IP "\(bu" 2
Mojolicious::Plugin::OpenAPI::SpecRenderer
.Sp
Plugin for exposing your spec in human readable or \s-1JSON\s0 format.
.IP "\(bu" 2
<https://www.openapis.org/>
.Sp
Official OpenAPI website.