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

DESCRIPTION

60       Mojolicious::Plugin::OpenAPI is Mojolicious::Plugin that add routes and
61       input/output validation to your Mojolicious application based on a
62       OpenAPI (Swagger) specification. This plugin supports both version 2.0
63       and 3.x, though 3.x might have some missing features.
64
65       Have a look at the "SEE ALSO" for references to more documentation.
66
67       Please report in issues <https://github.com/jhthorsen/json-
68       validator/issues> or open pull requests to enhance the 3.0 support.
69

HELPERS

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

HOOKS

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

RENDERER

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

ATTRIBUTES

147   route
148         $route = $openapi->route;
149
150       The parent Mojolicious::Routes::Route object for all the OpenAPI
151       endpoints.
152
153   validator
154         $jv = $openapi->validator;
155
156       Holds a JSON::Validator::OpenAPI::Mojolicious object.
157

METHODS

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

AUTHORS

279       Henrik Andersen
280
281       Ilya Rassadin
282
283       Jan Henning Thorsen
284
285       Joel Berger
286

COPYRIGHT AND LICENSE

288       Copyright (C) Jan Henning Thorsen
289
290       This program is free software, you can redistribute it and/or modify it
291       under the terms of the Artistic License version 2.0.
292