JSON::V...enAPIv2(3)

📦
version 5.150.0 · 8 versions
, in opensuse-leap 16.0

🌸 NAME 🌸

okay bestie, welcome to JSON::V...enAPIv2(3) from the User Contributed Perl Documentation — it's giving official manual, but make it make sense. This page is all about JSON::Validator::Schema::OpenAPIv2, aka OpenAPI version 2 / Swagger, and it's lowkey the blueprint for validating your API vibes. ✨

🦋 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 is literally the representation of <http://swagger.io/v2/schema.json> — that's the whole vibe. 🫶

👑 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 🌈

xoxo, your fav schema bestie 💅 — this iconic little page comes from perl v5.42.0, dated 2025-03-17, and the header/footer tag is JSON::V...enAPIv2(3). periodt. 🎀

📦 where this page comes from