SwaggerSocket Documentation

You can run a SwaggerSocket sample locally using the Maven Jetty plugin. By default, Jetty runs on port 8080. To specify a different port, use the jetty.port system property.

# Standard run on port 8080
% cd swaggersocket-{name}
% mvn jetty:run

# Run on a custom port (e.g., 9090)
% mvn -Djetty.port=9090 jetty:run

You can quickly explore the protocol by running pre-built distributions.

1. Unzip the distribution file.
2. Make the nettosphere.sh script executable.
3. Run the script.
4. Access the interface at http://127.0.0.1:8080.

Alternatively, you can build from source using Maven and run with Jetty (defaulting to Jetty 9, or use -Pjetty8 for Jetty 8):

% git clone https://github.com/swagger-api/swagger-socket.git
% cd swagger-socket
% mvn 
% cd samples/swaggersocket-{sample_name}
% mvn jetty:run

% unzip swaggersocket-{sample_name}-distribution.zip
  % chmod a+x ./bin/nettosphere.sh
  % ./bin/nettosphere.sh

To run the Wordnik Search Demo, you must provide a valid Wordnik API key. You can obtain one from http://developer.wordnik.com.

Depending on your deployment method, configure the key as follows:

Web Application

Add the following init-param to your web.xml file:

Nettosphere Shell

Pass the API key as a command-line argument when running the script, or run it without arguments to be prompted for the key (available in version 2.0.1+).

<!-- Web Application: web.xml configuration -->
<init-param>
    <param-name>com.wordnik.swagger.key</param-name>
    <param-value>${your-api-key}</param-value>
</init-param>

# Nettosphere Shell: command line usage
./bin/nettosphere.sh ${your-api-key}

You can run a sample using the NettoSphere embedded server by extracting the distribution zip file. The default port is 8080. To change the port, set the nettosphere.port system property via the DEV_OPTS environment variable.

# Standard run
% cd swaggersocket-{name}/target
% unzip swaggersocket-{name}-distribution.zip
% chmod a+x bin/nettosphere.sh
% ./bin/nettosphere.sh

# Run on a custom port (e.g., 9090) using DEV_OPTS
% export DEV_OPTS="-Dnettosphere.port=9090"
% ./bin/nettosphere.sh

This demo uses swaggerSocket.js to create a client that echoes messages back from a SwaggerSocket server.

Prerequisites:

1. A running SwaggerSocket server. You can use the swaggersocket-echo sample server found in the samples/swaggersocket-echo directory of this repository.
2. Node.js installed on your system.

Steps to run:

1. Navigate to the client source directory: src/main/resources.
2. Install the required client dependency: swaggersocket-client.
3. Execute the client script: echo-client.js.

% cd src/main/resources
% npm install swaggersocket-client
% node echo-client.js

To enable SwaggerSocket on your server, register the SwaggerSocketServlet in your web.xml. If you are using a framework like Jersey to load resources, you must also configure the package scanning via init-param.

<!-- Register the Servlet -->
<servlet>
    <description>SwaggerSocketServlet</description>
    <servlet-name>SwaggerSocketServlet</servlet-name>
    <servlet-class>com.wordnik.swaggersocket.server.SwaggerSocketServlet</servlet-class>
    <load-on-startup>0</load-on-startup>
</servlet>

<!-- Example: Configure Jersey package scanning -->
<servlet>
    ...
    <init-param>
        <param-name>com.sun.jersey.config.property.packages</param-name>
        <param-value>com.wordnik.swaggersocket.samples</param-value>
    </init-param>
</servlet>