1JSON::Validator::SchemaU:s:eOrpeCnoAnPtIrvi2b(u3t)ed PerJlSODNo:c:uVmaelnitdaattioorn::Schema::OpenAPIv2(3)
2
3
4

NAME

6       JSON::Validator::Schema::OpenAPIv2 - OpenAPI version 2 / Swagger
7

SYNOPSIS

9         use JSON::Validator;
10         my $schema = JSON::Validator->new->schema("...")->schema;
11
12         # Check for specification errors
13         my $errors = $schema->errors;
14
15         # 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
21         # 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

DESCRIPTION

28       This class represents <http://swagger.io/v2/schema.json>.
29

ATTRIBUTES

31   errors
32         my $array_ref = $schema->errors;
33
34       See "errors" in JSON::Validator::Schema.
35
36   moniker
37         $str    = $schema->moniker;
38         $schema = $schema->moniker("openapiv2");
39
40       Used to get/set the moniker for the given schema. Default value is
41       "openapiv2".
42
43   specification
44         my $str    = $schema->specification;
45         my $schema = $schema->specification($str);
46
47       Defaults to "<http://swagger.io/v2/schema.json>".
48

METHODS

50   add_default_response
51         $schema = $schema->add_default_response(\%params);
52
53       Used to add a default response schema for operations that does not
54       already have one. %params can be:
55
56       • description
57
58         The human readable description added to the operation.
59
60         Defaults: "Default response."
61
62       • name
63
64         The name used in the specification under "/components/schemas/".
65
66         Defaults: "DefaultResponse"
67
68       • schema
69
70         The schema to add. The default schema below might change, but the
71         basics will stay the same:
72
73           {
74             type: "object",
75             required: ["errors"],
76             properties: {
77               errors: {
78                 type: "array",
79                 items: {
80                   type: "object",
81                   required: ["message"],
82                   properties: {
83                     message: {type: "string"},
84                     path: {type: "string"}
85                   }
86                 }
87               }
88             }
89           }
90
91       • status
92
93         A list of status codes to apply the default schema to.
94
95         Default: "[400, 401, 404, 500, 501]".
96
97   base_url
98         $url = $schema->base_url;
99         $schema = $schema->base_url($url);
100
101       Can get or set the default URL for this schema. $url can be either a
102       Mojo::URL object or a plain string.
103
104       This method will read or write "basePath", "host" and/or "schemas" in
105       "data".
106
107   coerce
108         my $schema   = $schema->coerce({booleans => 1, numbers => 1, strings => 1});
109         my $hash_ref = $schema->coerce;
110
111       Coercion is enabled by default, since headers, path parts, query
112       parameters, ... are in most cases strings.
113
114       See also "coerce" in JSON::Validator.
115
116   new
117         $schema = JSON::Validator::Schema::OpenAPIv2->new(\%attrs);
118         $schema = JSON::Validator::Schema::OpenAPIv2->new;
119
120       Same as "new" in JSON::Validator::Schema, but will also build
121       L/coerce>.
122
123   parameters_for_request
124         $parameters = $schema->parameters_for_request([$method, $path]);
125
126       Finds all the request parameters defined in the schema, including
127       inherited parameters. Returns "undef" if the $path and $method cannot
128       be found.
129
130       Example return value:
131
132         [
133           {in => "query", name => "q"},
134           {in => "body", name => "body", accepts => ["application/json"]},
135         ]
136
137       The return value MUST not be mutated.
138
139   parameters_for_response
140         $array_ref = $schema->parameters_for_response([$method, $path, $status]);
141
142       Finds the response parameters defined in the schema. Returns "undef" if
143       the $path, $method and $status cannot be found. Will default to the
144       "default" response definition if $status could not be found and
145       "default" exists.
146
147       Example return value:
148
149         [
150           {in => "header", name => "X-Foo"},
151           {in => "body", name => "body", accepts => ["application/json"]},
152         ]
153
154       The return value MUST not be mutated.
155
156   routes
157         $collection = $schema->routes;
158
159       Used to gather all available routes in the schema and return them
160       sorted. The result is a Mojo::Collection object, where each item has a
161       hash looking like this:
162
163         {
164           method       => 'get',
165           path         => '/user/{id}',
166           operation_id => 'getUser', # Might be undef()
167         }
168
169   validate_request
170         @errors = $schema->validate_request([$method, $path], \%req);
171
172       This method can be used to validate a HTTP request. %req should contain
173       key/value pairs representing the request parameters. Example:
174
175         %req = (
176           body => sub {
177             my ($param_name, $param_for_request) = shift;
178             return {exists => 1, value => \%all_params} unless defined $param_name;
179             return {exists => 1, value => "..."};
180           },
181           formData => {email => "..."},
182           header => {"X-Request-Base" => "..."},
183           path => {id => "..."},
184           query => {limit => 42},
185         );
186
187       "formData", "header", "path" and "query" can be either a hash-ref, a
188       hash-like object or a code ref, while "body" MUST be a code ref. The
189       return value from the code ref will get mutated, making it possible to
190       check if an individual parameter was validated or not.
191
192         # Before: "exists" and "value" must be present
193         my @evaluated;
194         $req{query} =  sub { push @evaluated, {exists => 1, value => 42}, return $evaluated[-1] };
195
196         # Validate
197         $schema->validate_request(get => "/user"], \%req);
198
199         # After: "in", "name" and "valid" are added
200         $evaluated[-1] ==> {exists => 1, value => 42, in => "query", name => "foo", valid => 1};
201
202       A plain hash-ref will /not get mutated.
203
204       The body hash-ref can also have a "content_type" key. This will be
205       checked against the list of valid request or response content types in
206       the spec.
207
208   validate_response
209         @errors = $schema->validate_response([$method, $path, $status], \%res);
210
211       This method can be used to validate a HTTP response. %res should
212       contain key/value pairs representing the response parameters. Example:
213
214         %res = (
215           body => sub {
216             my ($param_name, $param_for_response) = shift;
217             return {exists => 1, value => \%all_params} unless defined $param_name;
218             return {accept => "application/json", exists => 1, value => "..."};
219           },
220           header => {"Location" => "..."},
221         );
222
223       %res follows the same rules as %req in "validate_request", but also
224       supports "accept", instead of specifying "content_type". "accept"
225       should have the same format as an "Accept" HTTP header.
226

SEE ALSO

228       JSON::Validator, Mojolicious::Plugin::OpenAPI,
229       <http://openapi-specification-visual-documentation.apihandyman.io/>
230
231
232
233perl v5.34.0                      2022-01-J2S1ON::Validator::Schema::OpenAPIv2(3)
Impressum