Provided by: libmojolicious-plugin-openapi-perl_5.09-1_all bug

NAME

       Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 - Mojolicious <3 OpenAPI v2 (Swagger)

OVERVIEW

       This guide will give you an introduction to how to use Mojolicious::Plugin::OpenAPI with OpenAPI version
       v2.

TUTORIAL

   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.

         {
           "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" }
                         }
                       }
                     }
                   }
                 }
               }
             }
           }
         }

       The complete HTTP request for getting the "pet list" will be "GET /api/pets" The first part of the path
       ("/api") comes from "basePath", the second part comes from the keys under "paths", and the HTTP method
       comes from the keys under "/pets".

       The different parts of the specification can also be retrieved as JSON using the "OPTIONS" HTTP method.
       Example:

         OPTIONS /api/pets
         OPTIONS /api/pets?method=get

       Note that the use of "OPTIONS" is EXPERIMENTAL, and subject to change.

       Here are some more details about the different keys:

       • swagger and info

         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.

       • host, schemes, consumes, produces, security and securityDefinitions

         These  keys  are currently not in use. "host" will be replaced by the "Host" header in the request. The
         rest of the keys are currently not in use.

         Submit an issue <https://github.com/jhthorsen/mojolicious-plugin-openapi/issues> if you have  ideas  on
         what to use these keys for.

       • basePath

         The  "basePath"  will also be used to add a route that renders back the specification either as JSON or
         HTML. Examples:

         • http://example.com/api.html

           Retrieve the expanded version of the API in human readable format. The formatting is currently a  bit
           rough, but should be easier than reading the JSON spec.

         • http://example.com/api.json

           Retrieve  the  expanded  version  of  the  API,  useful  for JavaScript clients and other client side
           applications.

       • parameters and responses

         "parameters" and "responses" will be used to define input and output validtion rules, which is used  by
         "openapi.input"  in  Mojolicious::Plugin::OpenAPI  and  when rendering the response back to the client,
         using "render(openapi => ...)".

         Have a look at "RENDERER" in Mojolicious::Plugin::OpenAPI for more details about output rendering.

       • operationId and x-mojo-name

         See "Route names".

       • x-mojo-placeholder

         "x-mojo-placeholder" can be used inside a parameter definition to instruct Mojolicious to parse a  path
         part in a certain way. Example:

           "parameters": [
             {
               "x-mojo-placeholder": "#",
               "in": "path",
               "name": "email",
               "type": "string"
             }
           ]

         See  Mojolicious::Guides::Routing  for  more  information  about  "standard",  "relaxed" and "wildcard"
         placeholders. The default is to use the "standard" ("/:foo") placeholder.

       • x-mojo-to

         The non-standard part in the spec above is "x-mojo-to". The "x-mojo-to"  key  can  be  either  a  plain
         string,  object  (hash)  or  an  array.  The  string  and  hash  will  be  passed  directly  to "to" in
         Mojolicious::Routes::Route, while the array ref will be flatten. Examples:

           "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"];

   Application
         package Myapp;
         use Mojo::Base "Mojolicious";

         sub startup {
           my $app = shift;
           $app->plugin("OpenAPI" => {url => $app->home->rel_file("myapi.json")});
         }

         1;

       The first thing in your code that you need to do is to load this  plugin  and  the  "Specification".  See
       "register" in Mojolicious::Plugin::OpenAPI for information about what the plugin config can be.

       See also "SYNOPSIS" in Mojolicious::Plugin::OpenAPI for example Mojolicious::Lite application.

   Controller
         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->{'x-opening-hour'} == (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;

       The  input will be validated using "openapi.valid_input" in Mojolicious::Plugin::OpenAPI while the output
       is validated through then openapi handler.

   Route names
       Routes will get its name from either "x-mojo-name" or from "operationId" if defined in the specification.

       The route name can also be used the other way around, to find already defined routes. This is  especially
       useful for Mojolicious::Lite apps.

       Note that if spec_route_name then all the route names will have that value as prefix:

         spec_route_name            = "my_cool_api"
         operationId or x-mojo-name = "Foo"
         Route name                 = "my_cool_api.Foo"

       You can also set "x-mojo-name" in the spec, instead of passing spec_route_name to plugin():

         {
           "swagger": "2.0",
           "info": { "version": "1.0", "title": "Some awesome API" },
           "x-mojo-name": "my_cool_api"
         }

   Default response schema
       A  default  response  definition  will be added to the API 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.

       See    "default_response_codes"    in   Mojolicious::Plugin::OpenAPI   and   "default_response_name"   in
       Mojolicious::Plugin::OpenAPI for more details on how to configure these settings.

       The response schema will be added to your spec like this, unless already defined:

         {
           ...
           "definitions": {
             ...
             "DefaultResponse": {
               "type":     "object",
               "required": ["errors"],
               "properties": {
                 "errors": {
                   "type":  "array",
                   "items": {
                     "type":       "object",
                     "required":   ["message"],
                     "properties": {"message": {"type": "string"}, "path": {"type": "string"}}
                   }
                 }
               }
             }
           }
         }

       The "errors" 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 "path", while the "message" is just to add some human readable
       debug information for why this request/response failed.

   Rendering binary data
       Rendering assets and binary data should be accomplished by using the standard Mojolicious tools:

         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);
         }

SEE ALSO

       Mojolicious::Plugin::OpenAPI, <https://openapis.org/specification>.

perl v5.36.0                                       2023-02-21              Mojolicious::P...ides::OpenAPIv2(3pm)