Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
JSON::Validator::SchemUserpContributed PeJSON::Validator::Schema::OpenAPIv2(3)

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:

       o description

	 The human readable description	added to the operation.

	 Defaults: "Default response."

       o name

	 The name used in the specification under "/components/schemas/".

	 Defaults: "DefaultResponse"

       o 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"}
		   }
		 }
	       }
	     }
	   }

       o status

	 A list	of status codes	to apply the default schema to.

	 Default: "[400, 401, 404, 500,	501]".

   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.

   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.

   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.

SEE ALSO
       JSON::Validator,	Mojolicious::Plugin::OpenAPI,
       <http://openapi-specification-visual-documentation.apihandyman.io/>

perl v5.32.1			  2021-09JSON::Validator::Schema::OpenAPIv2(3)

NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | METHODS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=JSON::Validator::Schema::OpenAPIv2&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help