JSON::Validator::Schema::OpenAPIv2(3pm)

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   moniker
32         $str    = $schema->moniker;
33         $schema = $schema->moniker("openapiv2");
34
35       Used to get/set the moniker for the given schema. Default value is
36       "openapiv2".
37
38   specification
39         my $str    = $schema->specification;
40         my $schema = $schema->specification($str);
41
42       Defaults to "<http://swagger.io/v2/schema.json>".
43

METHODS

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

NAME

SYNOPSIS

DESCRIPTION

ATTRIBUTES

METHODS

SEE ALSO