Provided by: libjson-validator-perl_5.10+dfsg-1_all 
NAME
JSON::Validator::Schema::OpenAPIv2 - OpenAPI version 2 / Swagger
SYNOPSIS
use JSON::Validator;
my $schema = JSON::Validator->new->schema("...")->schema;
# Check for specification errors
my $errors = $schema->errors;
# Returns a list of zero or more JSON::Validator::Error objects
my @request_errors = $schema->validate_request(
[get => "/path"],
{body => sub { return {exists => 1, value => {}} }},
);
# Returns a list of zero or more JSON::Validator::Error objects
my @response_errors = $schema->validate_response(
[get => "/path", 200],
{body => sub { return {exists => 1, value => {}} }},
);
DESCRIPTION
This class represents <http://swagger.io/v2/schema.json>.
ATTRIBUTES
errors
my $array_ref = $schema->errors;
See "errors" in JSON::Validator::Schema.
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>".
METHODS
add_default_response
$schema = $schema->add_default_response(\%params);
Used to add a default response schema for operations that does not already have one.
%params can be:
• description
The human readable description added to the operation.
Defaults: "Default response."
• name
The name used in the specification under "/components/schemas/".
Defaults: "DefaultResponse"
• schema
The schema to add. The default schema below might change, but the basics will stay the
same:
{
type: "object",
required: ["errors"],
properties: {
errors: {
type: "array",
items: {
type: "object",
required: ["message"],
properties: {
message: {type: "string"},
path: {type: "string"}
}
}
}
}
}
• status
A list of status codes to apply the default schema to.
Default: "[400, 401, 404, 500, 501]".
base_url
$url = $schema->base_url;
$schema = $schema->base_url($url);
Can get or set the default URL for this schema. $url can be either a Mojo::URL object or a
plain string.
This method will read or write "basePath", "host" and/or "schemas" in "data".
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.
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 ($name, $param) = shift;
# $param = {name => $name, in => ..., schema => ..., ...}
return {exists => 1, value => \%all_params} unless defined $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 ($name, $param) = shift;
# $param = {name => $name, in => ..., ...}
return {exists => 1, value => \%all_params} unless defined $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.
SEE ALSO
JSON::Validator, Mojolicious::Plugin::OpenAPI,
<http://openapi-specification-visual-documentation.apihandyman.io/>