view release on metacpan or  search on metacpan

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

          else {
            return $c->$cb('Api Key header not present');
          }
        }
      }
    }
  );

=back

=head3 References with files

Only a file reference like

  "$ref": "my-other-cool-component.json#/components/schemas/inputSchema"

Is supported, though a valid path must be used for both the reference and in the
referenced file, in order to produce a valid spec output.

See L<Known Issues/File references> for unsupported file references

=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> is 
used 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>:

  {
    "openapi": "3.0.2",
    "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:

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