1Mojolicious::Plugin::OpUesneArPIC(o3n)tributed Perl DocuMmoejnotlaitciioonus::Plugin::OpenAPI(3)
2
3
4
6 Mojolicious::Plugin::OpenAPI - OpenAPI / Swagger plugin for Mojolicious
7
9 use Mojolicious::Lite;
10
11 # Will be moved under "basePath", resulting in "POST /api/echo"
12 post "/echo" => sub {
13
14 # Validate input request or return an error document
15 my $c = shift->openapi->valid_input or return;
16
17 # Generate some data
18 my $data = {body => $c->req->json};
19
20 # Validate the output response and render it to the user agent
21 # using a custom "openapi" handler.
22 $c->render(openapi => $data);
23 }, "echo";
24
25 # Load specification and start web server
26 plugin OpenAPI => {url => "data:///spec.json"};
27 app->start;
28
29 __DATA__
30 @@ spec.json
31 {
32 "swagger" : "2.0",
33 "info" : { "version": "0.8", "title" : "Echo Service" },
34 "schemes" : [ "http" ],
35 "basePath" : "/api",
36 "paths" : {
37 "/echo" : {
38 "post" : {
39 "x-mojo-name" : "echo",
40 "parameters" : [
41 { "in": "body", "name": "body", "schema": { "type" : "object" } }
42 ],
43 "responses" : {
44 "200": {
45 "description": "Echo response",
46 "schema": { "type": "object" }
47 }
48 }
49 }
50 }
51 }
52 }
53
54 See Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 or
55 Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv3 for more information
56 about.
57
58 Looking at the documentation for "x-mojo-to" in
59 Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 can be especially
60 useful if you are using extensions (formats) such as ".json". The logic
61 is the same for OpenAPIv2 and OpenAPIv3.
62
64 Mojolicious::Plugin::OpenAPI is Mojolicious::Plugin that add routes and
65 input/output validation to your Mojolicious application based on a
66 OpenAPI (Swagger) specification. This plugin supports both version 2.0
67 and 3.x, though 3.x might have some missing features.
68
69 Have a look at the "SEE ALSO" for references to more documentation.
70
71 Please report in issues <https://github.com/jhthorsen/json-
72 validator/issues> or open pull requests to enhance the 3.0 support.
73
75 openapi.spec
76 $hash = $c->openapi->spec($json_pointer)
77 $hash = $c->openapi->spec("/info/title")
78 $hash = $c->openapi->spec;
79
80 Returns the OpenAPI specification. A JSON Pointer can be used to
81 extract a given section of the specification. The default value of
82 $json_pointer will be relative to the current operation. Example:
83
84 {
85 "paths": {
86 "/pets": {
87 "get": {
88 // This datastructure is returned by default
89 }
90 }
91 }
92 }
93
94 openapi.validate
95 @errors = $c->openapi->validate;
96
97 Used to validate a request. @errors holds a list of
98 JSON::Validator::Error objects or empty list on valid input.
99
100 Note that this helper is only for customization. You probably want
101 "openapi.valid_input" in most cases.
102
103 openapi.valid_input
104 $c = $c->openapi->valid_input;
105
106 Returns the Mojolicious::Controller object if the input is valid or
107 automatically render an error document if not and return false. See
108 "SYNOPSIS" for example usage.
109
111 Mojolicious::Plugin::OpenAPI will emit the following hooks on the
112 application object.
113
114 openapi_routes_added
115 Emitted after all routes have been added by this plugin.
116
117 $app->hook(openapi_routes_added => sub {
118 my ($openapi, $routes) = @_;
119
120 for my $route (@$routes) {
121 ...
122 }
123 });
124
125 This hook is EXPERIMENTAL and subject for change.
126
128 This plugin register a new handler called "openapi". The special thing
129 about this handler is that it will validate the data before sending it
130 back to the user agent. Examples:
131
132 $c->render(json => {foo => 123}); # without validation
133 $c->render(openapi => {foo => 123}); # with validation
134
135 This handler will also use "renderer" to format the output data. The
136 code below shows the default "renderer" which generates JSON data:
137
138 $app->plugin(
139 OpenAPI => {
140 renderer => sub {
141 my ($c, $data) = @_;
142 return Mojo::JSON::encode_json($data);
143 }
144 }
145 );
146
148 route
149 $route = $openapi->route;
150
151 The parent Mojolicious::Routes::Route object for all the OpenAPI
152 endpoints.
153
154 validator
155 $jv = $openapi->validator;
156
157 Holds either a JSON::Validator::Schema::OpenAPIv2 or a
158 JSON::Validator::Schema::OpenAPIv3 object.
159
161 register
162 $openapi = $openapi->register($app, \%config);
163 $openapi = $app->plugin(OpenAPI => \%config);
164
165 Loads the OpenAPI specification, validates it and add routes to $app.
166 It will also set up "HELPERS" and adds a before_render hook for auto-
167 rendering of error documents. The return value is the object instance,
168 which allow you to access the "ATTRIBUTES" after you load the plugin.
169
170 %config can have:
171
172 coerce
173
174 See "coerce" in JSON::Validator for possible values that "coerce" can
175 take.
176
177 Default: booleans,numbers,strings
178
179 The default value will include "defaults" in the future, once that is
180 stable enough.
181
182 default_response
183
184 Instructions for "add_default_response_schema" in
185 JSON::Validator::Schema::OpenAPIv2. (Also used for OpenAPIv3)
186
187 format
188
189 Set this to a default list of file extensions that your API accepts.
190 This value can be overwritten by "x-mojo-to" in
191 Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2.
192
193 This config parameter is EXPERIMENTAL and subject for change.
194
195 log_level
196
197 "log_level" is used when logging invalid request/response error
198 messages.
199
200 Default: "warn".
201
202 op_spec_to_route
203 "op_spec_to_route" can be provided if you want to add route definitions
204 without using "x-mojo-to". Example:
205
206 $app->plugin(OpenAPI => {op_spec_to_route => sub {
207 my ($plugin, $op_spec, $route) = @_;
208
209 # Here are two ways to customize where to dispatch the request
210 $route->to(cb => sub { shift->render(openapi => ...) });
211 $route->to(ucfirst "$op_spec->{operationId}#handle_request");
212 }});
213
214 This feature is EXPERIMENTAL and might be altered and/or removed.
215
216 plugins
217
218 A list of OpenAPI classes to extend the functionality. Default is:
219 Mojolicious::Plugin::OpenAPI::Cors,
220 Mojolicious::Plugin::OpenAPI::SpecRenderer and
221 Mojolicious::Plugin::OpenAPI::Security.
222
223 $app->plugin(OpenAPI => {plugins => [qw(+Cors +SpecRenderer +Security)]});
224
225 You can load your own plugins by doing:
226
227 $app->plugin(OpenAPI => {plugins => [qw(+SpecRenderer My::Cool::OpenAPI::Plugin)]});
228
229 renderer
230
231 See "RENDERER".
232
233 route
234
235 "route" can be specified in case you want to have a protected API.
236 Example:
237
238 $app->plugin(OpenAPI => {
239 route => $app->routes->under("/api")->to("user#auth"),
240 url => $app->home->rel_file("cool.api"),
241 });
242
243 skip_validating_specification
244
245 Used to prevent calling "errors" in JSON::Validator::Schema::OpenAPIv2
246 for the specification.
247
248 spec_route_name
249
250 Name of the route that handles the "basePath" part of the specification
251 and serves the specification. Defaults to "x-mojo-name" in the
252 specification at the top level.
253
254 url
255
256 See "schema" in JSON::Validator for the different "url" formats that is
257 accepted.
258
259 "spec" is an alias for "url", which might make more sense if your
260 specification is written in perl, instead of JSON or YAML.
261
262 version_from_class
263
264 Can be used to overridden "/info/version" in the API specification,
265 from the return value from the "VERSION()" method in
266 "version_from_class".
267
268 Defaults to the current $app. This can be disabled by setting the
269 "version_from_class" to zero (0).
270
272 Henrik Andersen
273
274 Ilya Rassadin
275
276 Jan Henning Thorsen
277
278 Joel Berger
279
281 Copyright (C) Jan Henning Thorsen
282
283 This program is free software, you can redistribute it and/or modify it
284 under the terms of the Artistic License version 2.0.
285
287 • Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2
288
289 Guide for how to use this plugin with OpenAPI version 2.0 spec.
290
291 • Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv3
292
293 Guide for how to use this plugin with OpenAPI version 3.0 spec.
294
295 • Mojolicious::Plugin::OpenAPI::Cors
296
297 Plugin to add Cross-Origin Resource Sharing (CORS).
298
299 • Mojolicious::Plugin::OpenAPI::Security
300
301 Plugin for handling security definitions in your schema.
302
303 • Mojolicious::Plugin::OpenAPI::SpecRenderer
304
305 Plugin for exposing your spec in human readble or JSON format.
306
307 • <https://www.openapis.org/>
308
309 Official OpenAPI website.
310
311
312
313perl v5.34.0 2022-01-21 Mojolicious::Plugin::OpenAPI(3)