1JSON::Validator::SchemaU:s:eOrpeCnoAnPtIrvi2b(u3t)ed PerJlSODNo:c:uVmaelnitdaattioorn::Schema::OpenAPIv2(3)
2
6 JSON::Validator::Schema::OpenAPIv2 - OpenAPI version 2 / Swagger
7
9 use JSON::Validator;
10 my $schema = JSON::Validator->new->schema("...")->schema;
11 # Check for specification errors
13 my $errors = $schema->errors;
14 # Returns a list of zero or more JSON::Validator::Error objects
16 my @request_errors = $schema->validate_request(
17 [get => "/path"],
18 {body => sub { return {exists => 1, value => {}} }},
19 );
20 # Returns a list of zero or more JSON::Validator::Error objects
22 my @response_errors = $schema->validate_response(
23 [get => "/path", 200],
24 {body => sub { return {exists => 1, value => {}} }},
25 );
26
28 This class represents <http://swagger.io/v2/schema.json>.
29
31 moniker
32 $str = $schema->moniker;
33 $schema = $schema->moniker("openapiv2");
34 Used to get/set the moniker for the given schema. Default value is
36 "openapiv2".
37 specification
39 my $str = $schema->specification;
40 my $schema = $schema->specification($str);
41 Defaults to "<http://swagger.io/v2/schema.json>".
43
45 allow_invalid_ref
46 $bool = $schema->allow_invalid_ref;
47 $schema = $schema->allow_invalid_ref(1);
48 Setting this to true will replace all $refs in the schema before
50 validating it. This can be useful if you have a complex schema that you
51 want to split into different files where OpenAPIv2 normally does not
52 allow you to.
53 Setting this attribute will not work if the schema has recursive $refs.
55 This method is highly EXPERIMENTAL, and it is not advices to use this
57 method.
58 coerce
60 my $schema = $schema->coerce({booleans => 1, numbers => 1, strings => 1});
61 my $hash_ref = $schema->coerce;
62 Coercion is enabled by default, since headers, path parts, query
64 parameters, ... are in most cases strings.
65 See also "coerce" in JSON::Validator.
67 data
69 my $hash_ref = $schema->data;
70 my $schema = $schema->data($bool);
71 my $schema = $schema->data($hash_ref);
72 my $schema = $schema->data($url);
73 Same as "JSON::Validator::Schema/data", but will bundle the schema if
75 "allow_invalid_ref" is set.
76 new
78 $schema = JSON::Validator::Schema::OpenAPIv2->new(\%attrs);
79 $schema = JSON::Validator::Schema::OpenAPIv2->new;
80 Same as "new" in JSON::Validator::Schema, but will also build
82 L/coerce>.
83 parameters_for_request
85 $parameters = $schema->parameters_for_request([$method, $path]);
86 Finds all the request parameters defined in the schema, including
88 inherited parameters. Returns "undef" if the $path and $method cannot
89 be found.
90 Example return value:
92 [
94 {in => "query", name => "q"},
95 {in => "body", name => "body", accepts => ["application/json"]},
96 ]
97 The return value MUST not be mutated.
99 parameters_for_response
101 $array_ref = $schema->parameters_for_response([$method, $path, $status]);
102 Finds the response parameters defined in the schema. Returns "undef" if
104 the $path, $method and $status cannot be found. Will default to the
105 "default" response definition if $status could not be found and
106 "default" exists.
107 Example return value:
109 [
111 {in => "header", name => "X-Foo"},
112 {in => "body", name => "body", accepts => ["application/json"]},
113 ]
114 The return value MUST not be mutated.
116 validate_request
118 @errors = $schema->validate_request([$method, $path], \%req);
119 This method can be used to validate a HTTP request. %req should contain
121 key/value pairs representing the request parameters. Example:
122 %req = (
124 body => sub {
125 my ($param_name, $param_for_request) = shift;
126 return {exists => 1, value => \%all_params} unless defined $param_name;
127 return {exists => 1, value => "..."};
128 },
129 formData => {email => "..."},
130 header => {"X-Request-Base" => "..."},
131 path => {id => "..."},
132 query => {limit => 42},
133 );
134 "formData", "header", "path" and "query" can be either a hash-ref, a
136 hash-like object or a code ref, while "body" MUST be a code ref. The
137 return value from the code ref will get mutated, making it possible to
138 check if an individual parameter was validated or not.
139 # Before: "exists" and "value" must be present
141 my @evaluated;
142 $req{query} = sub { push @evaluated, {exists => 1, value => 42}, return $evaluated[-1] };
143 # Validate
145 $schema->validate_request(get => "/user"], \%req);
146 # After: "in", "name" and "valid" are added
148 $evaluated[-1] ==> {exists => 1, value => 42, in => "query", name => "foo", valid => 1};
149 A plain hash-ref will /not get mutated.
151 The body hash-ref can also have a "content_type" key. This will be
153 checked against the list of valid request or response content types in
154 the spec.
155 validate_response
157 @errors = $schema->validate_response([$method, $path, $status], \%res);
158 This method can be used to validate a HTTP response. %res should
160 contain key/value pairs representing the response parameters. Example:
161 %res = (
163 body => sub {
164 my ($param_name, $param_for_response) = shift;
165 return {exists => 1, value => \%all_params} unless defined $param_name;
166 return {accept => "application/json", exists => 1, value => "..."};
167 },
168 header => {"Location" => "..."},
169 );
170 %res follows the same rules as %req in "validate_request", but also
172 supports "accept", instead of specifying "content_type". "accept"
173 should have the same format as an "Accept" HTTP header.
174
176 JSON::Validator, Mojolicious::Plugin::OpenAPI,
177 <http://openapi-specification-visual-documentation.apihandyman.io/>
178perl v5.32.1 2021-01-J3S1ON::Validator::Schema::OpenAPIv2(3)