moniker

  $str    = $schema->moniker;
  $schema = $schema->moniker("openapiv2");

Used to get/set the moniker for the given schema. Default value is "openapiv2".

specification

  my $str    = $schema->specification;
  my $schema = $schema->specification($str);

Defaults to "<http://swagger.io/v2/schema.json>".

allow_invalid_ref

  $bool   = $schema->allow_invalid_ref;
  $schema = $schema->allow_invalid_ref(1);

Setting this to true will replace all $refs in the schema before validating it. This can be useful if you have a complex schema that you want to split into different files where OpenAPIv2 normally does not allow you to.

Setting this attribute will not work if the schema has recursive $refs.

This method is highly EXPERIMENTAL, and it is not advices to use this method.

coerce

  my $schema   = $schema->coerce({booleans => 1, numbers => 1, strings => 1});
  my $hash_ref = $schema->coerce;

Coercion is enabled by default, since headers, path parts, query parameters, ... are in most cases strings.

See also "coerce" in JSON::Validator.

data

  my $hash_ref = $schema->data;
  my $schema   = $schema->data($bool);
  my $schema   = $schema->data($hash_ref);
  my $schema   = $schema->data($url);

Same as "JSON::Validator::Schema/data", but will bundle the schema if "allow_invalid_ref" is set.

new

  $schema = JSON::Validator::Schema::OpenAPIv2->new(\%attrs);
  $schema = JSON::Validator::Schema::OpenAPIv2->new;

Same as "new" in JSON::Validator::Schema, but will also build L/coerce>.

parameters_for_request

  $parameters = $schema->parameters_for_request([$method, $path]);

Finds all the request parameters defined in the schema, including inherited parameters. Returns "undef" if the $path and $method cannot be found.

Example return value:

  [
    {in => "query", name => "q"},
    {in => "body", name => "body", accepts => ["application/json"]},
  ]

The return value MUST not be mutated.

parameters_for_response

  $array_ref = $schema->parameters_for_response([$method, $path, $status]);

Finds the response parameters defined in the schema. Returns "undef" if the $path, $method and $status cannot be found. Will default to the "default" response definition if $status could not be found and "default" exists.

Example return value:

  [
    {in => "header", name => "X-Foo"},
    {in => "body", name => "body", accepts => ["application/json"]},
  ]

The return value MUST not be mutated.

routes

  $collection = $schema->routes;

Used to gather all available routes in the schema and return them sorted. The result is a Mojo::Collection object, where each item has a hash looking like this:

  {
    method       => 'get',
    path         => '/user/{id}',
    operation_id => 'getUser', # Might be undef()
  }

validate_request

  @errors = $schema->validate_request([$method, $path], \%req);

This method can be used to validate a HTTP request. %req should contain key/value pairs representing the request parameters. Example:

  %req = (
    body => sub {
      my ($param_name, $param_for_request) = shift;
      return {exists => 1, value => \%all_params} unless defined $param_name;
      return {exists => 1, value => "..."};
    },
    formData => {email => "..."},
    header => {"X-Request-Base" => "..."},
    path => {id => "..."},
    query => {limit => 42},
  );

"formData", "header", "path" and "query" can be either a hash-ref, a hash-like object or a code ref, while "body" MUST be a code ref. The return value from the code ref will get mutated, making it possible to check if an individual parameter was validated or not.

  # Before: "exists" and "value" must be present
  my @evaluated;
  $req{query} =  sub { push @evaluated, {exists => 1, value => 42}, return $evaluated[-1] };
  # Validate
  $schema->validate_request(get => "/user"], \%req);
  # After: "in", "name" and "valid" are added
  $evaluated[-1] ==> {exists => 1, value => 42, in => "query", name => "foo", valid => 1};

A plain hash-ref will /not get mutated.

The body hash-ref can also have a "content_type" key. This will be checked against the list of valid request or response content types in the spec.

validate_response

  @errors = $schema->validate_response([$method, $path, $status], \%res);

This method can be used to validate a HTTP response. %res should contain key/value pairs representing the response parameters. Example:

  %res = (
    body => sub {
      my ($param_name, $param_for_response) = shift;
      return {exists => 1, value => \%all_params} unless defined $param_name;
      return {accept => "application/json", exists => 1, value => "..."};
    },
    header => {"Location" => "..."},
  );

%res follows the same rules as %req in "validate_request", but also supports "accept", instead of specifying "content_type". "accept" should have the same format as an "Accept" HTTP header.