restify-swagger-jsdoc

Create Swagger documentation page based on jsdoc

Installation

:warning: Check your restify version

If you use a restify version prior to v7, you must use the following command:

npm install restify-swagger-jsdoc@^1

Else you can use the following command:

npm install restify-swagger-jsdoc

Initialization

Minimal example

To initialize the swagger JSDoc page, simply add these lines to the file that loads your restify server :

var restifySwaggerJsdoc = require('restify-swagger-jsdoc');
restifySwaggerJsdoc.createSwaggerPage({
    title: 'API documentation', // Page title
    version: '1.0.0', // Server version
    server: server, // Restify server instance created with restify.createServer()
    path: '/docs/swagger' // Public url where the swagger page will be available
});

With these settings, assuming that your server listens on port 80, the Swagger documentation page will be available at http://localhost/docs/swagger.
The swagger.json file is available at http://localhost/docs/swagger/swagger.json.

See below for a complete list of supported parameters.

Supported parameters

|Name|Type|Required|Description|Default value| |-----|:-----:|:-----:|-----|-----| |title|string|Required|Page title|| |version|string|Required|Server version|| |server|Server|Required|Restify server instance created with restify.createServer()|| |path|string|Required|Public url where the swagger page will be available|| |description|string|Optional|A short description of the application|''| |tags|Tag[]|Optional|A list of tags used by the specification with additional metadata|[]| |host|string|Optional|The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths|undefined| |schemes|string[]|Optional|The transfer protocol of the API. Values MUST be from the list: 'http', 'https', 'ws', 'wss'|[]| |apis|string[]|Optional|Path(s) to the API docs|[]| |definitions|Definitions|Optional|External definitions to add to swagger|[]| |routePrefix|string|Optional|Prefix to add for all routes|''| |forceSecure|boolean|Optional|Force swagger-ui to use https protocol to load JSON file|false| |validatorUrl|string|Optional|Validate specs against given validator, set to null to disable validation|'https://online.swagger.io/validator'| |supportedSubmitMethods|string[]|Optional|List of HTTP methods that have the Try it out feature enabled. An empty array disables Try it out for all operations|['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']| |securityDefinitions|SecurityDefinitions|Optional|List of authentication methods available for the current API, available when clicking on the "Authorize" button on the UI (more detail here)|undefined|

How to document the API

This module is based on swagger-jsdoc, so you can refer to this module's documentation to document your API.