wordnik/swagger-ui — pull request #170 by pose (2013-03-22 21:16:55+00:00)
Title: Adding Support for Websockets

(This pull request depends on: https://github.com/wordnik/swagger.js/pull/24)

## Adding support for trying WebSockets from the Swagger UI

A new field named `protocols` is added to the spec. This is a list of the supported protocols on that endpoint. This field must be set in order to indicate that the operation uses WebSocket protocol (`ws` or `wss`). Other possible valid values for the field are: 'http' and 'https'. I'm following some guidelines based on [this comment](https://gist.github.com/pose/7d481e6d509630127e6a#comment-760732) by @fehguy

For example:

```json

{
"apiVersion": "0.2",
"swaggerVersion": "1.1",
"basePath": "http://0.0.0.0:8001",
"resourcePath": "/pet",
"apis": [
{
"path": "/testWebSocket",
"description": "Sample WebSocket",
"operations": [
{
"httpMethod": "GET",
"protocols": ["ws"],
"summary": "Test sample socket",
"notes": "Example to show websocket behavior",
"responseClass": "Pet",
"nickname": "testWebSocket",
"parameters": [
{
"description": "Pet object that needs to be added to the store",
"paramType": "body",
"required": true,
"allowMultiple": false,
"dataType": "Pet"
}
],
"errorResponses": [
{
"code": 404,
"reason": "Pet not found"
}
]
}
]
},
...

```

Currently, only the `ws` protocol is supported.

### UI Changes
* A new button is introduced when the WebSocket connection is established. This is the `close` button and will allow to end the bi-directional communication.
* As the example shows, a body parameter is supported and can be specified in order to send a first message when the connection is established.
* As a new message arrives it's appended to the `response body` field. The user is scrolled to the last message.
* More sanitization over the fields is applied. There are some replacements of the unsafe jQuery `.html()` with the `.text()` method.
* In the case of the WebSocket communication, the `response code` and `response headers` are hidden.

### Sample App to test this changes

Create a new folder with the following `package.json`:

```json
{
"name": "socket-server",
"version": "0.0.1",
"dependencies": {
"websocket": "*"
}
}
```

In the same folder, create a file named `index.js` with the following content:

```js
var WebSocketServer = require('websocket').server,
http = require('http');

var server = http.createServer(function (request, response) {});

server.listen(8001);

var wsServer = new WebSocketServer({
httpServer: server
});

wsServer.on('request', function(request) {
var connection = request.accept(null, request.origin);
setInterval(function () {
var d = {x: Math.random(), y: Math.random()};
connection.sendUTF(JSON.stringify(d));
}, 1000);

connection.on('message', function(message) {
console.log(message);
});

connection.on('close', function(connection) {
// close user connection
});
});

```

Run the following commands in you favorite shell:

```sh
npm install . && node index.js
```
After, that create a `resource.json` that describes that service. For instance:

```json
{
"apiVersion": "0.2",
"swaggerVersion": "1.1",
"basePath": "http://0.0.0.0:8000",
"apis": [
{
"path": "/pet.json",
"description": ""
}
]
}
```

And a `pet.json`:

```json
{
"apiVersion": "0.2",
"swaggerVersion": "1.1",
"basePath": "http://0.0.0.0:8001",
"resourcePath": "/pet",
"apis": [
{
"path": "/testWebSocket",
"description": "Sample WebSocket",
"operations": [
{
"httpMethod": "GET",
"protocols": ["ws"],
"summary": "Test sample socket",
"notes": "Example to show websocket behavior",
"responseClass": "Pet",
"nickname": "testWebSocket",
"parameters": [
]
}
]
}
]
}

```
Host those files (you can use `python -m SimpleHTTPServer` to serve the contents of a folder) and point the SwaggerUI there. Open `pet -> testWebSocket` and click `Try it out!`.