apidoc-plugin-websocket

Only a simple websocket plugin for apidoc. you can make websocket request directly at document pages generated by apidoc and this plugin to test your interface.

apidoc search in global node modules dir and local node_modules for modules that start with apidoc-plugin-. (local installed plugins have higher priority)

Install

Make sure the old versions has been removed!

 npm uninstall apidoc-plugin-bic-ws

then install the current:

 npm install apidoc-plugin-websocket --save-dev

Run

After install this pulgin in right position, run apidoc in your apidoc.json directory like this:

apidoc -i example -t ./node_modules/apidoc-plugin-websocket/template

Arg example is your source directory path and the default apidoc/template must be replaced with apidoc-plugin-websocket/template because of incompatible.

Configuration

Enhance Tag

@api [{type}] cmd:func your_api_title

Permited value for type is:

• get
• post
• websocket
• get,websocket
• post,websocket

New Tag

@apiWebsocket arg

Permited value for arg is:

• boolean
• {cmd:func} url
• {cmd:func}
• url

Example Use

In case websocket request only

Declare request type in @api tag and provide a server address using @apiWebsocket tag,

/**
 * @api {websocket} do:somthing for do somthing
 * @apiGroup User
 * @apiName doSomething
 * @apiWebsocket ws://localhost:8082
 */

Optional,you can turn on the websocket request for all interfaces by adding a single line to apidoc.json:

"wsRequest": "ws://localhost:8082"

after it we simplified the configuration:

/**
 * @api {websocket} do:somthing for do somthing
 * @apiGroup User
 * @apiName doSomething
 */

well, go a step further:

/**
 * @api do:somthing for do somthing
 * @apiGroup User
 * @apiName doSomething
 */

maybe there is a subpath in ws server address,we need @apiWebsocket again:

/**
 * @api do:somthing for do somthing
 * @apiGroup User
 * @apiName doSomething
 * @apiWebsocket /subpath
 */

That's all!combining wsRequest and subpath is the duty of the plugin

Case of websocket and http request both

Sometimes,we hava to support http and websocket interface meanwhile,there is only a little more thing to do it.for http interface,use @api as a native way,then add the websocket to {type} block such as:

/**
 * @api {get,websocket} user/look look a user
 * @apiGroup User
 * @apiName lookUser
 */

or if you want to custom websocket info, @apiWebsocket come again:

/**
 * @api {get,websocket} user/find find a user
 * @apiGroup User
 * @apiName findUser
 * @apiWebsocket {ws_user:ws_find}
 */

Global Settings

the wsRequest key-vlaue in apidoc.json file like this

"wsRequest": "ws://localhost:8082"

behaves just as the way as sampleUrl; it applied by plugin automatically unless you turn off at method level:

/**
 * @apiWebsocket false
 */

Note

• this plugin work with the handlebars template,so have to run with -t opation.
• all changes powered by apidoc worker and parser extension,see parser and worker directory for detail.