--- name: "JSON::Validator::Schema::OpenAPIv2" section: "3pm" platform: "linux" package: "libjson-validator-perl" version: "5.15+dfsg-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/JSON::Validator::Schema::OpenAPIv2" --- # JSON::Validator::Schema::OpenAPIv2(3pm) OpenAPI version 2 / Swagger ## 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 \. ## 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 "\". ## 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, \