Mojolicious::Plugin::OpenAPI(3pm)

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         # Use "v3" instead of "v2" for "schema" if you are using OpenAPI v3
27         # The plugin must be loaded *after* defining the routes in a Lite app
28         plugin OpenAPI => {url => "data:///spec.json", schema => "v2"};
29         app->start;
30
31         __DATA__
32         @@ spec.json
33         {
34           "swagger" : "2.0",
35           "info" : { "version": "0.8", "title" : "Echo Service" },
36           "schemes" : [ "http" ],
37           "basePath" : "/api",
38           "paths" : {
39             "/echo" : {
40               "post" : {
41                 "x-mojo-name" : "echo",
42                 "parameters" : [
43                   { "in": "body", "name": "body", "schema": { "type" : "object" } }
44                 ],
45                 "responses" : {
46                   "200": {
47                     "description": "Echo response",
48                     "schema": { "type": "object" }
49                   }
50                 }
51               }
52             }
53           }
54         }
55
56       See Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 or
57       Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv3 for tutorials on how to
58       write a "full" app with application class and controllers.
59

IMPORTANT ANNOUNCEMENT

61       Next version of Mojolicious::Plugin::OpenAPI will not be shipped with
62       JSON::Validator::OpenAPI::Mojolicious. Instead, it will depend on the
63       new JSON::Validator::Schema::OpenAPIv2 and
64       JSON::Validator::Schema::OpenAPIv3 modules.
65
66       The next version is available at
67       <https://github.com/jhthorsen/mojolicious-plugin-openapi/pull/160>.
68

DESCRIPTION

70       Mojolicious::Plugin::OpenAPI is Mojolicious::Plugin that add routes and
71       input/output validation to your Mojolicious application based on a
72       OpenAPI (Swagger) specification. This plugin supports both version 2.0
73       and 3.x, though 3.x might have some missing features.
74
75       Have a look at the "SEE ALSO" for references to more documentation.
76
77       Please report in issues <https://github.com/jhthorsen/json-
78       validator/issues> or open pull requests to enhance the 3.0 support.
79

HELPERS

81   openapi.spec
82         $hash = $c->openapi->spec($json_pointer)
83         $hash = $c->openapi->spec("/info/title")
84         $hash = $c->openapi->spec;
85
86       Returns the OpenAPI specification. A JSON Pointer can be used to
87       extract a given section of the specification. The default value of
88       $json_pointer will be relative to the current operation. Example:
89
90         {
91           "paths": {
92             "/pets": {
93               "get": {
94                 // This datastructure is returned by default
95               }
96             }
97           }
98         }
99
100   openapi.validate
101         @errors = $c->openapi->validate;
102
103       Used to validate a request. @errors holds a list of
104       JSON::Validator::Error objects or empty list on valid input.
105
106       Note that this helper is only for customization. You probably want
107       "openapi.valid_input" in most cases.
108
109   openapi.valid_input
110         $c = $c->openapi->valid_input;
111
112       Returns the Mojolicious::Controller object if the input is valid or
113       automatically render an error document if not and return false. See
114       "SYNOPSIS" for example usage.
115

HOOKS

117       Mojolicious::Plugin::OpenAPI will emit the following hooks on the
118       application object.
119
120   openapi_routes_added
121       Emitted after all routes have been added by this plugin.
122
123         $app->hook(openapi_routes_added => sub {
124           my ($openapi, $routes) = @_;
125
126           for my $route (@$routes) {
127             ...
128           }
129         });
130
131       This hook is EXPERIMENTAL and subject for change.
132

RENDERER

134       This plugin register a new handler called "openapi". The special thing
135       about this handler is that it will validate the data before sending it
136       back to the user agent. Examples:
137
138         $c->render(json => {foo => 123});    # without validation
139         $c->render(openapi => {foo => 123}); # with validation
140
141       This handler will also use "renderer" to format the output data. The
142       code below shows the default "renderer" which generates JSON data:
143
144         $app->plugin(
145           OpenAPI => {
146             renderer => sub {
147               my ($c, $data) = @_;
148               return Mojo::JSON::encode_json($data);
149             }
150           }
151         );
152

ATTRIBUTES

154   route
155         $route = $openapi->route;
156
157       The parent Mojolicious::Routes::Route object for all the OpenAPI
158       endpoints.
159
160   validator
161         $jv = $openapi->validator;
162
163       Holds a JSON::Validator::OpenAPI::Mojolicious object.
164

METHODS

166   register
167         $openapi = $openapi->register($app, \%config);
168         $openapi = $app->plugin(OpenAPI => \%config);
169
170       Loads the OpenAPI specification, validates it and add routes to $app.
171       It will also set up "HELPERS" and adds a before_render hook for auto-
172       rendering of error documents. The return value is the object instance,
173       which allow you to access the "ATTRIBUTES" after you load the plugin.
174
175       %config can have:
176
177       allow_invalid_ref
178
179       The OpenAPI specification does not allow "$ref" at every level, but
180       setting this flag to a true value will ignore the $ref check.
181
182       Note that setting this attribute is discourage.
183
184       coerce
185
186       See "coerce" in JSON::Validator for possible values that "coerce" can
187       take.
188
189       Default: booleans,numbers,strings
190
191       The default value will include "defaults" in the future, once that is
192       stable enough.
193
194       default_response_codes
195
196       A list of response codes that will get a "$ref" pointing to
197       "#/definitions/DefaultResponse", unless already defined in the spec.
198       "DefaultResponse" can be altered by setting "default_response_name".
199
200       The default response code list is the following:
201
202         400 | Bad Request           | Invalid input from client / user agent
203         401 | Unauthorized          | Used by Mojolicious::Plugin::OpenAPI::Security
204         404 | Not Found             | Route is not defined
205         500 | Internal Server Error | Internal error or failed output validation
206         501 | Not Implemented       | Route exists, but the action is not implemented
207
208       Note that more default codes might be added in the future if required
209       by the plugin.
210
211       default_response_name
212
213       The name of the "definition" in the spec that will be used for
214       "default_response_codes". The default value is "DefaultResponse". See
215       "Default response schema" in
216       Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 for more details.
217
218       log_level
219
220       "log_level" is used when logging invalid request/response error
221       messages.
222
223       Default: "warn".
224
225       plugins
226
227       A list of OpenAPI classes to extend the functionality. Default is:
228       Mojolicious::Plugin::OpenAPI::Cors,
229       Mojolicious::Plugin::OpenAPI::SpecRenderer and
230       Mojolicious::Plugin::OpenAPI::Security.
231
232         $app->plugin(OpenAPI => {plugins => [qw(+Cors +SpecRenderer +Security)]});
233
234       You can load your own plugins by doing:
235
236         $app->plugin(OpenAPI => {plugins => [qw(+SpecRenderer My::Cool::OpenAPI::Plugin)]});
237
238       renderer
239
240       See "RENDERER".
241
242       route
243
244       "route" can be specified in case you want to have a protected API.
245       Example:
246
247         $app->plugin(OpenAPI => {
248           route => $app->routes->under("/api")->to("user#auth"),
249           url   => $app->home->rel_file("cool.api"),
250         });
251
252       schema
253
254       Can be used to set a different schema, than the default OpenAPI 2.0
255       spec.  Example values: "http://swagger.io/v2/schema.json", "v2" or
256       "v3".
257
258       See also Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 and
259       Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv3.
260
261       spec_route_name
262
263       Name of the route that handles the "basePath" part of the specification
264       and serves the specification. Defaults to "x-mojo-name" in the
265       specification at the top level.
266
267       url
268
269       See "schema" in JSON::Validator for the different "url" formats that is
270       accepted.
271
272       "spec" is an alias for "url", which might make more sense if your
273       specification is written in perl, instead of JSON or YAML.
274
275       version_from_class
276
277       Can be used to overridden "/info/version" in the API specification,
278       from the return value from the "VERSION()" method in
279       "version_from_class".
280
281       This will only have an effect if "version" is "0".
282
283       Defaults to the current $app.
284

AUTHORS

286       Henrik Andersen
287
288       Ilya Rassadin
289
290       Jan Henning Thorsen
291
292       Joel Berger
293

COPYRIGHT AND LICENSE

295       Copyright (C) Jan Henning Thorsen
296
297       This program is free software, you can redistribute it and/or modify it
298       under the terms of the Artistic License version 2.0.
299