.\" 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::Guides::OpenAPIv2 3pm"
.TH Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 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::Guides::OpenAPIv2 \- Mojolicious <3 OpenAPI v2 (Swagger)
.SH "OVERVIEW"
.IX Header "OVERVIEW"
This guide will give you an introduction to how to use
Mojolicious::Plugin::OpenAPI with OpenAPI version v2.
.SH "TUTORIAL"
.IX Header "TUTORIAL"
.SS "Specification"
.IX Subsection "Specification"
This plugin reads an OpenAPI specification <https://openapis.org/specification>
and generate routes and input/output rules from it. See JSON::Validator for
supported schema file formats.
.PP
.Vb 10
\&  {
\&    "swagger": "2.0",
\&    "info": { "version": "1.0", "title": "Some awesome API" },
\&    "basePath": "/api",
\&    "paths": {
\&      "/pets": {
\&        "get": {
\&          "operationId": "getPets",
\&          "x\-mojo\-name": "get_pets",
\&          "x\-mojo\-to": "pet#list",
\&          "summary": "Finds pets in the system",
\&          "parameters": [
\&            {"in": "body", "name": "body", "schema": {"type": "object"}},
\&            {"in": "query", "name": "age", "type": "integer"}
\&          ],
\&          "responses": {
\&            "200": {
\&              "description": "Pet response",
\&              "schema": {
\&                "type": "object",
\&                "properties": {
\&                  "pets": {
\&                    "type": "array",
\&                    "items": { "type": "object" }
\&                  }
\&                }
\&              }
\&            }
\&          }
\&        }
\&      }
\&    }
\&  }
.Ve
.PP
The complete \s-1HTTP\s0 request for getting the \*(L"pet list\*(R" will be \f(CW\*(C`GET /api/pets\*(C'\fR
The first part of the path (\*(L"/api\*(R") comes from \f(CW\*(C`basePath\*(C'\fR, the second part
comes from the keys under \f(CW\*(C`paths\*(C'\fR, and the \s-1HTTP\s0 method comes from the keys
under \f(CW\*(C`/pets\*(C'\fR.
.PP
The different parts of the specification can also be retrieved as \s-1JSON\s0 using
the \*(L"\s-1OPTIONS\*(R" HTTP\s0 method. Example:
.PP
.Vb 2
\&  OPTIONS /api/pets
\&  OPTIONS /api/pets?method=get
.Ve
.PP
Note that the use of \*(L"\s-1OPTIONS\*(R"\s0 is \s-1EXPERIMENTAL,\s0 and subject to change.
.PP
Here are some more details about the different keys:
.IP "\(bu" 2
swagger and info
.Sp
These two sections are required to make the specification valid. Check out
<https://github.com/OAI/OpenAPI\-Specification/blob/master/versions/2.0.md>
for a complete reference to the specification.
.IP "\(bu" 2
host, schemes, consumes, produces, security and securityDefinitions
.Sp
These keys are currently not in use. \*(L"host\*(R" will be replaced by the \*(L"Host\*(R"
header in the request. The rest of the keys are currently not in use.
.Sp
Submit an issue <https://github.com/jhthorsen/mojolicious-plugin-openapi/issues>
if you have ideas on what to use these keys for.
.IP "\(bu" 2
basePath
.Sp
The \f(CW\*(C`basePath\*(C'\fR will also be used to add a route that renders back the
specification either as \s-1JSON\s0 or \s-1HTML.\s0 Examples:
.RS 2
.IP "\(bu" 2
http://example.com/api.html
.Sp
Retrieve the expanded version of the \s-1API\s0 in human readable format. The
formatting is currently a bit rough, but should be easier than reading the \s-1JSON\s0
spec.
.IP "\(bu" 2
http://example.com/api.json
.Sp
Retrieve the expanded version of the \s-1API,\s0 useful for JavaScript clients and
other client side applications.
.RE
.RS 2
.RE
.IP "\(bu" 2
parameters and responses
.Sp
\&\f(CW\*(C`parameters\*(C'\fR and \f(CW\*(C`responses\*(C'\fR will be used to define input and output
validtion rules, which is used by \*(L"openapi.input\*(R" in Mojolicious::Plugin::OpenAPI
and when rendering the response back to the client, using \f(CW\*(C`render(openapi => ...)\*(C'\fR.
.Sp
Have a look at \*(L"\s-1RENDERER\*(R"\s0 in Mojolicious::Plugin::OpenAPI for more details about
output rendering.
.IP "\(bu" 2
operationId and x\-mojo-name
.Sp
See \*(L"Route names\*(R".
.IP "\(bu" 2
x\-mojo-placeholder
.Sp
\&\f(CW\*(C`x\-mojo\-placeholder\*(C'\fR can be used inside a parameter definition to instruct
Mojolicious to parse a path part in a certain way. Example:
.Sp
.Vb 8
\&  "parameters": [
\&    {
\&      "x\-mojo\-placeholder": "#",
\&      "in": "path",
\&      "name": "email",
\&      "type": "string"
\&    }
\&  ]
.Ve
.Sp
See Mojolicious::Guides::Routing for more information about \*(L"standard\*(R",
\&\*(L"relaxed\*(R" and \*(L"wildcard\*(R" placeholders. The default is to use the \*(L"standard\*(R"
(\*(L"/:foo\*(R") placeholder.
.IP "\(bu" 2
x\-mojo-to
.Sp
The non-standard part in the spec above is \*(L"x\-mojo-to\*(R". The \*(L"x\-mojo-to\*(R" key
can be either a plain string, object (hash) or an array. The string and hash
will be passed directly to \*(L"to\*(R" in Mojolicious::Routes::Route, while the array
ref will be flatten. Examples:
.Sp
.Vb 2
\&  "x\-mojo\-to": "pet#list"
\&  $route\->to("pet#list");
\&
\&  "x\-mojo\-to": {"controller": "pet", "action": "list", "foo": 123}
\&  $route\->to({controller => "pet", action => "list", foo => 123);
\&
\&  "x\-mojo\-to": ["pet#list", {"foo": 123}, ["format": ["json"]]]
\&  $route\->to("pet#list", {foo => 123});
\&  $route\->pattern\->constraints\->{format} = ["json"];
.Ve
.SS "Application"
.IX Subsection "Application"
.Vb 2
\&  package Myapp;
\&  use Mojo::Base "Mojolicious";
\&
\&  sub startup {
\&    my $app = shift;
\&    $app\->plugin("OpenAPI" => {url => $app\->home\->rel_file("myapi.json")});
\&  }
\&
\&  1;
.Ve
.PP
The first thing in your code that you need to do is to load this plugin and the
\&\*(L"Specification\*(R". See \*(L"register\*(R" in Mojolicious::Plugin::OpenAPI for information
about what the plugin config can be.
.PP
See also \*(L"\s-1SYNOPSIS\*(R"\s0 in Mojolicious::Plugin::OpenAPI for example
Mojolicious::Lite application.
.SS "Controller"
.IX Subsection "Controller"
.Vb 2
\&  package Myapp::Controller::Pet;
\&  use Mojo::Base "Mojolicious::Controller";
\&
\&  sub list {
\&
\&    # Do not continue on invalid input and render a default 400
\&    # error document.
\&    my $c = shift\->openapi\->valid_input or return;
\&
\&    # You might want to introspect the specification for the current route
\&    my $spec = $c\->openapi\->spec;
\&    unless ($spec\->{\*(Aqx\-opening\-hour\*(Aq} == (localtime)[2]) {
\&      return $c\->render(openapi => [], status => 498);
\&    }
\&
\&    my $age  = $c\->param("age");
\&    my $body = $c\->req\->json;
\&
\&    # $output will be validated by the OpenAPI spec before rendered
\&    my $output = {pets => [{name => "kit\-e\-cat"}]};
\&    $c\->render(openapi => $output);
\&  }
\&
\&  1;
.Ve
.PP
The input will be validated using
\&\*(L"openapi.valid_input\*(R" in Mojolicious::Plugin::OpenAPI while the output is
validated through then openapi
handler.
.SS "Route names"
.IX Subsection "Route names"
Routes will get its name from either \*(L"x\-mojo-name\*(R" or from \*(L"operationId\*(R" if
defined in the specification.
.PP
The route name can also be used the other way around, to find already defined
routes. This is especially useful for Mojolicious::Lite apps.
.PP
Note that if spec_route_name
then all the route names will have that value as prefix:
.PP
.Vb 3
\&  spec_route_name            = "my_cool_api"
\&  operationId or x\-mojo\-name = "Foo"
\&  Route name                 = "my_cool_api.Foo"
.Ve
.PP
You can also set \*(L"x\-mojo-name\*(R" in the spec, instead of passing
spec_route_name
to \fBplugin()\fR:
.PP
.Vb 5
\&  {
\&    "swagger": "2.0",
\&    "info": { "version": "1.0", "title": "Some awesome API" },
\&    "x\-mojo\-name": "my_cool_api"
\&  }
.Ve
.SS "Default response schema"
.IX Subsection "Default response schema"
A default response definition will be added to the \s-1API\s0 spec, unless it's
already defined. This schema will at least be used for invalid input (400 \- Bad Request) and
invalid output (500 \- Internal Server Error), but can also be used in other cases.
.PP
See \*(L"default_response_codes\*(R" in Mojolicious::Plugin::OpenAPI and
\&\*(L"default_response_name\*(R" in Mojolicious::Plugin::OpenAPI for more details on how
to configure these settings.
.PP
The response schema will be added to your spec like this, unless already defined:
.PP
.Vb 10
\&  {
\&    ...
\&    "definitions": {
\&      ...
\&      "DefaultResponse": {
\&        "type":     "object",
\&        "required": ["errors"],
\&        "properties": {
\&          "errors": {
\&            "type":  "array",
\&            "items": {
\&              "type":       "object",
\&              "required":   ["message"],
\&              "properties": {"message": {"type": "string"}, "path": {"type": "string"}}
\&            }
\&          }
\&        }
\&      }
\&    }
\&  }
.Ve
.PP
The \*(L"errors\*(R" key will contain one element for all the invalid data, and not
just the first one. The useful part for a client is mostly the \*(L"path\*(R", while
the \*(L"message\*(R" is just to add some human readable debug information for why this
request/response failed.
.SS "Rendering binary data"
.IX Subsection "Rendering binary data"
Rendering assets and binary data should be accomplished by using the standard
Mojolicious tools:
.PP
.Vb 3
\&  sub get_image {
\&    my $c = shift\->openapi\->valid_input or return;
\&    my $asset = Mojo::Asset::File\->new(path => "image.jpeg");
\&
\&    $c\->res\->headers\->content_type("image/jpeg");
\&    $c\->reply\->asset($asset);
\&  }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious::Plugin::OpenAPI,
<https://openapis.org/specification>.