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

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.