Swagger2::Guides::WebSocket - How to expose Swagger over WebSockets
This guide will show how to expose a Swagger API over WebSockets.
This feature is EXPERIMENTAL and is subject to change.
This way of exposing Swagger over WebSockets is in no way compatible with https://github.com/swagger-api/swagger-socket.
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 $ws is then passed on to the plugin and set up with a default route variable swagger.
$ws
The reason why we create a custom websocket route is so it can be used bi-directional, instead of just dispatching to Swagger actions.
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 json event which can dispatch_to_swagger.
This method will return boolean true if the input looks like a Swagger 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.
{ "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".
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); } };
"x-mojo-around-action" is ignored when issuing WebSocket requests. This may be changed in future version.
Sharing a WebSocket route object between multiple Swagger plugins is unsupported. (The outcome is unknown)
The protocol and implementation is subject for change. feedback is highly appreciated.
Jan Henning Thorsen - jhthorsen@cpan.org
jhthorsen@cpan.org
To install Swagger2, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Swagger2
CPAN shell
perl -MCPAN -e shell install Swagger2
For more information on module installation, please visit the detailed CPAN module installation guide.