view release on metacpan or  search on metacpan

lib/Mojolicious/Plugin/OpenAPI/Guides/OpenAPIv2.pod  view on Meta::CPAN

("/:foo") placeholder.

=item * 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 L<Mojolicious::Routes::Route/to>, 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"];

=back

=head2 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
L</Specification>. See L<Mojolicious::Plugin::OpenAPI/register> for information
about what the plugin config can be.

See also L<Mojolicious::Plugin::OpenAPI/SYNOPSIS> for example
L<Mojolicious::Lite> application.

=head2 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
L<Mojolicious::Plugin::OpenAPI/openapi.valid_input> while the output is
validated through then L<openapi|Mojolicious::Plugin::OpenAPI/RENDERER>
handler.

=head2 Route names

Routes will get its name from either L</x-mojo-name> or from L</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 L<Mojolicious::Lite> apps.

Note that if L<spec_route_name|Mojolicious::Plugin::OpenAPI/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
L<spec_route_name|Mojolicious::Plugin::OpenAPI/spec_route_name>
to L<plugin()|Mojolicious::Plugin::OpenAPI/register>:

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

=head2 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 L<Mojolicious::Plugin::OpenAPI/default_response_codes> and
L<Mojolicious::Plugin::OpenAPI/default_response_name> 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"}}
            }
          }
        }
      }
    }
  }