1Mojolicious::Plugin::OpUesneArPIC(o3n)tributed Perl DocuMmoejnotlaitciioonus::Plugin::OpenAPI(3)
2
3
4

NAME

6       Mojolicious::Plugin::OpenAPI - OpenAPI / Swagger plugin for Mojolicious
7

SYNOPSIS

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

DESCRIPTION

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

HELPERS

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

HOOKS

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

RENDERER

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

ATTRIBUTES

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

METHODS

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

AUTHORS

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

SEE ALSO

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)
Impressum