/usr/share/perl5/Swagger2/Guides/WebSocket.pod is in libswagger2-perl 0.73-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 | =head1 NAME
Swagger2::Guides::WebSocket - How to expose Swagger over WebSockets
=head1 OVERVIEW
This guide will show how to expose a Swagger API over WebSockets.
This feature is EXPERIMENTAL and is subject to change.
=head1 DISCLAIMER
This way of exposing Swagger over WebSockets is in no way compatible with
L<https://github.com/swagger-api/swagger-socket>.
=head1 SYNOPSIS
=head2 Application
package MyApp;
use Mojo::Base "Mojolicious";
sub startup {
my $app = shift;
my $ws = $app->routes->websocket("/ws")->to("events#ws");
$app->plugin(Swagger2 => {
url => app->home->rel_file("api.yaml"),
ws => $ws,
});
}
In the example application class above, we create a custom route object for
handling the WebSocket request. The route object C<$ws> is then passed on to
the L<plugin|Mojolicious::Plugin::Swagger2> and set up with a default route
variable L<swagger|Mojolicious::Plugin::Swagger2/STASH VARIABLES>.
The reason why we create a custom websocket route is so it can be used
bi-directional, instead of just dispatching to Swagger actions.
=head2 Controller
package MyApp::Controller::Events;
sub ws {
my $c = shift;
$c->on(json => sub {
my ($c, $data) = @_;
return if $c->dispatch_to_swagger($data);
});
}
In the example controller above we listen to a L<json|Mojolicious::Controller/on>
event which can L<dispatch_to_swagger|Mojolicious::Plugin::Swagger2/dispatch_to_swagger>.
This method will return boolean true if the input looks like a Swagger request.
=head2 Request
The input data to the WebSocket need to be JSON and look like this:
{
"id": "some unique string",
"op": "operationId",
"params": {
"paramerName": "value"
}
}
The "id" is used to map the response to a unique request. This means that the
"id" need to be generated on the client side. The uniqueness requirement is
only for this WebSocket connection.
"op" need to match an operationId in the Swagger specification.
"params" must be an object where the keys match the parameters in the Swagger
specification.
=head2 Response
{
"id": "some unique string",
"code": 200,
"body": {"any":"thing"}
}
The response contains the input "id", the HTTP status "code" and the response
from the Swagger action inside "body".
=head2 JavaScript example
Here is an example JavaScript which can communicate over the socket:
var ws = new WebSocket("ws://example.com/ws");
ws.onopen = function () {
ws.send(JSON.stringify({
id: "42",
op: "listPets",
args: {limit: 60}
});
};
ws.onmessage = function (e) {
var data = JSON.parse(e.data);
if (data.id == "42") {
// Response from the request above, because of matching "id"
console.log(data.code, data.body);
}
};
=head1 CAVEATS
=over 4
=item *
"x-mojo-around-action" is ignored when issuing WebSocket requests. This may be
changed in future version.
=item *
Sharing a WebSocket route object between multiple Swagger plugins is
unsupported. (The outcome is unknown)
=item *
The protocol and implementation is subject for change.
L<feedback|https://github.com/jhthorsen/swagger2/issues> is highly appreciated.
=back
=head1 AUTHOR
Jan Henning Thorsen - C<jhthorsen@cpan.org>
=cut
|