restify-swagger-jsdoc

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 --production

Else you can use the following command:

npm install restify-swagger-jsdoc --production

Initialization

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

var restifySwaggerJsdoc = require('restify-swagger-jsdoc');
restifySwaggerJsdoc.createSwaggerPage({
    title: 'API documentation', // Page title (required)
    version: '1.0.0', // Server version (required)
    server: server, // Restify server instance created with restify.createServer() (required)
    path: '/docs/swagger', // Public url where the swagger page will be available (required)
    description: 'My great app', // A short description of the application. (default: '')
    tags: [{ // A list of tags used by the specification with additional metadata (default: [])
        name: 'Tag name',
        description: 'Tag description'
    }],
    host: 'google.com', // The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths.
    schemes: [], // The transfer protocol of the API. Values MUST be from the list: 'http', 'https', 'ws', 'wss'. (default: [])
    apis: [ `${__dirname}/controllers/*.js` ], // Path to the API docs (default: [])
    definitions: {myObject: require('api/myObject.json')}, // External definitions to add to swagger (default: [])
    routePrefix: 'prefix', // Prefix to add for all routes (default: '')
    forceSecure: false, // Force swagger-ui to use https protocol to load JSON file (default: false)
    validatorUrl: 'http://example.com', // Validate specs against given validator, set to null to disable validation (default: 'https://online.swagger.io/validator')
    supportedSubmitMethods: ['get', 'post'] // List of HTTP methods that have the Try it out feature enabled. An empty array disables Try it out for all operations. (default: ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'])
});

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.

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.