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         # It is recommended to use Mojolicious::Plugin::OpenAPI with a "full app".
10         # See the links after this example for more information.
11         use Mojolicious::Lite;
12
13         # Because the route name "echo" matches the "x-mojo-name", this route
14         # will be moved under "basePath", resulting in "POST /api/echo"
15         post "/echo" => sub {
16
17           # Validate input request or return an error document
18           my $c = shift->openapi->valid_input or return;
19
20           # Generate some data
21           my $data = {body => $c->req->json};
22
23           # Validate the output response and render it to the user agent
24           # using a custom "openapi" handler.
25           $c->render(openapi => $data);
26         }, "echo";
27
28         # Load specification and start web server
29         plugin OpenAPI => {url => "data:///swagger.yaml"};
30         app->start;
31
32         __DATA__
33         @@ swagger.yaml
34         swagger: "2.0"
35         info: { version: "0.8", title: "Echo Service" }
36         schemes: ["https"]
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              responses:
45                200:
46                  description: "Echo response"
47                  schema: { type: "object" }
48
49       See Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 or
50       Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv3 for more in depth
51       information about how to use Mojolicious::Plugin::OpenAPI with a "full
52       app".  Even with a "lite app" it can be very useful to read those
53       guides.
54
55       Looking at the documentation for "x-mojo-to" in
56       Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2 can be especially
57       useful. (The logic is the same for OpenAPIv2 and OpenAPIv3)
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 plugins and other
66       useful documentation.
67
68       Please report in issues <https://github.com/jhthorsen/json-
69       validator/issues> or open pull requests to enhance the 3.0 support.
70

HELPERS

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

HOOKS

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

RENDERER

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

ATTRIBUTES

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

METHODS

158   register
159         $openapi = $openapi->register($app, \%config);
160         $openapi = $app->plugin(OpenAPI => \%config);
161
162       Loads the OpenAPI specification, validates it and add routes to $app.
163       It will also set up "HELPERS" and adds a before_render hook for auto-
164       rendering of error documents. The return value is the object instance,
165       which allow you to access the "ATTRIBUTES" after you load the plugin.
166
167       %config can have:
168
169       coerce
170
171       See "coerce" in JSON::Validator for possible values that "coerce" can
172       take.
173
174       Default: booleans,numbers,strings
175
176       The default value will include "defaults" in the future, once that is
177       stable enough.
178
179       default_response
180
181       Instructions for "add_default_response_schema" in
182       JSON::Validator::Schema::OpenAPIv2. (Also used for OpenAPIv3)
183
184       format
185
186       Set this to a default list of file extensions that your API accepts.
187       This value can be overwritten by "x-mojo-to" in
188       Mojolicious::Plugin::OpenAPI::Guides::OpenAPIv2.
189
190       This config parameter is EXPERIMENTAL and subject for change.
191
192       log_level
193
194       "log_level" is used when logging invalid request/response error
195       messages.
196
197       Default: "warn".
198
199       op_spec_to_route
200
201       "op_spec_to_route" can be provided if you want to add route definitions
202       without using "x-mojo-to". Example:
203
204         $app->plugin(OpenAPI => {op_spec_to_route => sub {
205           my ($plugin, $op_spec, $route) = @_;
206
207           # Here are two ways to customize where to dispatch the request
208           $route->to(cb => sub { shift->render(openapi => ...) });
209           $route->to(ucfirst "$op_spec->{operationId}#handle_request");
210         }});
211
212       This feature is EXPERIMENTAL and might be altered and/or removed.
213
214       plugins
215
216       A list of OpenAPI classes to extend the functionality. Default is:
217       Mojolicious::Plugin::OpenAPI::Cors,
218       Mojolicious::Plugin::OpenAPI::SpecRenderer and
219       Mojolicious::Plugin::OpenAPI::Security.
220
221         $app->plugin(OpenAPI => {plugins => [qw(+Cors +SpecRenderer +Security)]});
222
223       You can load your own plugins by doing:
224
225         $app->plugin(OpenAPI => {plugins => [qw(+SpecRenderer My::Cool::OpenAPI::Plugin)]});
226
227       renderer
228
229       See "RENDERER".
230
231       route
232
233       "route" can be specified in case you want to have a protected API.
234       Example:
235
236         $app->plugin(OpenAPI => {
237           route => $app->routes->under("/api")->to("user#auth"),
238           url   => $app->home->rel_file("cool.api"),
239         });
240
241       skip_validating_specification
242
243       Used to prevent calling "errors" in JSON::Validator::Schema::OpenAPIv2
244       for the specification.
245
246       spec_route_name
247
248       Name of the route that handles the "basePath" part of the specification
249       and serves the specification. Defaults to "x-mojo-name" in the
250       specification at the top level.
251
252       spec, url
253
254       See "schema" in JSON::Validator for the different "url" formats that is
255       accepted.
256
257       "spec" is an alias for "url", which might make more sense if your
258       specification is written in perl, instead of JSON or YAML.
259
260       Here are some common uses:
261
262         $app->plugin(OpenAPI => {url  => $app->home->rel_file('openapi.yaml'));
263         $app->plugin(OpenAPI => {url  => 'https://example.com/swagger.json'});
264         $app->plugin(OpenAPI => {spec => JSON::Validator::Schema::OpenAPIv3->new(...)});
265         $app->plugin(OpenAPI => {spec => {swagger => "2.0", paths => {...}, ...}});
266
267       version_from_class
268
269       Can be used to overridden "/info/version" in the API specification,
270       from the return value from the "VERSION()" method in
271       "version_from_class".
272
273       Defaults to the current $app. This can be disabled by setting the
274       "version_from_class" to zero (0).
275

AUTHORS

277       Henrik Andersen
278
279       Ilya Rassadin
280
281       Jan Henning Thorsen
282
283       Joel Berger
284

COPYRIGHT AND LICENSE

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