restify-swagger-jsdoc
v3.3.0
Published
Create Swagger documentation page based on jsdoc
Downloads
2,520
Readme
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.