Programmatically generate your Swagger specification (JSON) file.

A library that allows you to programmatically annotate your existing express api with swagger info and then generate and validate your json spec file. All without completely starting over or changing the structure of your express routes.

Why

There are already a few libraries out there to add Swagger documentation to your express api, like swagger-node-express and swagger-node which work really well, however they require you to either start from scratch or change your routes to work with their format. This libary is different and can easily be added to an existing and established express api using the normal patterns you are used to.

##Installation Requires Express 4.x

Install the package:

npm install swagger-spec-express --save-exact

Basic code example:

var express = require ( ' express ' ) ; var swagger = require ( ' swagger-spec-express ' ) ; var packageJson = require ( ' ./package.json ' ) ; var app = express ( ) ; var options = { title : packageJson . title , version : packageJson . version } ; swagger . initialise ( app , options ) ; app . get ( ' /swagger.json ' , function ( err , res ) { res . status ( 200 ) . json ( swagger . json ( ) ) ; } ) . describe ( { responses : { 200 : { description : " Returns the swagger.json document " } } } ) ; swagger . compile ( ) ; var port = 3000 ; app . listen ( port , appListening ) ; function appListening ( ) { console . info ( packageJson . name + ' is listening on port ' + port ) ; }

This will create a very basic express app that serves up the swagger.json document when you navigate to http://localhost:3000/swagger.json

The JSON Schema file that will be used to validate the supplied metadata on the route can be found here in addition the fields are detailed below. Wherever possible the library tries to adhear to the official Swagger Specification so that is a good place to look for extra information about what you can specify.

Describing Your Routes

As seen above, once you have called initialise on your app, the describe method is automatically added and can be added to routes you declare directly on your app object.

But what if you want to use the router object? In the above example code above add the following to the top of the page:

var exampleRouter = require ( ' ./example-route ' ) ;

And then after calling swagger.initialise(app, options); add the following:

app . use ( exampleRouter ) ;

Code for the example router:

' use strict ' ; var express = require ( ' express ' ) ; var swagger = require ( ' swagger-spec-express ' ) ; var router = new express . Router ( ) ; swagger . swaggerize ( router ) ; module . exports = router ; router . get ( ' /one ' , function ( req , res ) { res . status ( 200 ) . json ( { example : 1 } ) } ) . describe ( { responses : { 200 : { description : " Returns example 1 " } } } ) ;

Adding the UI

Simply follow the instructions for the official Swagger UI project. or use your favourite, alternative Swagger UI theme.

API

Table of Contents

initialise

lib/initialise.js:120-136

Will initialise your app with the required swaggers-spec information. In addition you can pass in some options which will be used when generating the swagger JSON document later on. Both British and American spelling supported.

Parameters

Examples

Minimal

var express = require ( ' express ' ) ; var swagger = require ( ' swagger-spec-express ' ) ; var packageJson = require ( ' ./package.json ' ) ; var app = express ( ) ; swagger . initialise ( app , options ) ;

Extensive

var express = require ( ' express ' ) ; var swagger = require ( ' swagger-spec-express ' ) ; var packageJson = require ( ' ./package.json ' ) ; var app = express ( ) ; var options = { document : { } , title : packageJson . title , description : packageJson . description , termsOfService : ' You may only use this api for reasons! ' , contact : { name : ' ' , url : ' ' , email : ' ' } , license : { name : ' ' , url : ' ' } , version : packageJson . version , host : ' localhost ' , basePath : ' / ' , schemes : [ ' http ' , ' https ' ] , consumes : [ ' application/json ' ] , produces : [ ' application/json ' ] , paths : { } , definitions : { } , parameters : { } , responses : { } , securityDefinitions : { basicAuth : { type : " basic " , description : " HTTP Basic Authentication. Works over HTTPS " } } , security : [ { basicAuth : [ ] } ] , defaultSecurity : " basicAuth " , tags : [ { name : ' My Manual Tag ' , description : ' Manually added to swagger ' , externalDocs : { description : ' This doc describes how to make tags ' , url : ' https://github.com/eXigentCoder/swagger-spec-express ' } } ] , externalDocs : { description : ' This doc describes how to use swagger spec express ' , url : ' https://github.com/eXigentCoder/swagger-spec-express ' } } ; swagger . initialise ( app , options ) ;

Throws Error if already initialised, should call reset first if reinitialisation required

if already initialised, should call reset first if reinitialisation required Throws Error if no app object provided

if no app object provided Throws Error if no options object provided

Returns void

swaggerise

lib/swaggerise.js:16-68

Adds the .describe function onto the provided object. The object should either be an express app or express router.

Parameters

item object the item to apply

Examples

var swagger = require ( ' swagger-spec-express ' ) ; var express = require ( ' express ' ) ; var app = express ( ) ; swagger . swaggerize ( app ) ; var router = new express . Router ( ) ; swagger . swaggerize ( router ) ;

Returns void

describe

lib/swaggerise.js:62-67

Allows you describe an app our router route.

Parameters

metaData object Metadata about a route. At least one of metaData.responses or metaData.common.responses must be specified. metaData.summary [string] A brief summary of the operation. metaData.description [string] A longer description of the operation, GitHub Flavored Markdown is allowed. metaData.externalDocs [object] information about external documentation metaData.externalDocs.description [string] A short description of the target documentation. GFM syntax can be used for rich text representation. metaData.externalDocs.url string Required. The URL for the target documentation. Value MUST be in the format of a URL. metaData.operationId [string] A unique identifier of the operation. metaData.produces [Array<string>] A list of MIME types the API can produce. metaData.consumes [Array<string>] A list of MIME types the API can consume. metaData.parameters [(object | string)] An object to hold parameters that can be used across operations. This property does not define global parameters for all operations. See Parameter Definitions Object. metaData.tags [Array<string>] A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared may be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. See Tag Object. metaData.schemes [Array<string>] The transfer protocol of the API. metaData.deprecated [boolean] Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is false. metaData.security [(array | boolean | string)] A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition. See Security Requirement Object. metaData.common [object] A collection of common data to include in this route. metaData.common.responses [Array<string>] Common responses as added by calling common.addResponse metaData.common.parameters [object] A collection of common parameters to use for this route. metaData.common.parameters.header [Array<string>] A common header parameter as added by calling common.parameters.addHeader metaData.common.parameters.body [Array<string>] A common body parameter as added by calling common.parameters.addBody metaData.common.parameters.query [Array<string>] A common query string parameter as added by calling common.parameters.addQuery metaData.common.parameters.formData [Array<string>] A common form data parameter as added by calling common.parameters.addFormData metaData.responses [object] Response objects names can either be any valid HTTP status code or 'default'.

Metadata about a route. At least one of metaData.responses or metaData.common.responses must be specified. metaData.common.parameters.path [Array<string>] A common path parameter as added by calling common.parameters.addPath

Examples

var swagger = require ( ' swagger-spec-express ' ) ; var express = require ( ' express ' ) ; var router = new express . Router ( ) ; swagger . swaggerize ( router ) ; router . get ( ' / ' , function ( req , res ) { } ) . describe ( { } ) ;

Returns void

compile

lib/index.js:52-59

Will gather together all your described app routes and compile them into a single document to be served up by your api when you call json . Can only be called once initialise has been called. Should only call this once you have completely finished describing your routes.

Examples

var swagger = require ( ' swagger-spec-express ' ) ; var express = require ( ' express ' ) ; var router = new express . Router ( ) ; swagger . swaggerize ( router ) ; router . get ( ' / ' , function ( req , res ) { } ) . describe ( { } ) ; swagger . compile ( ) ;

Throws Error Will throw an error if initialise wasn't called or if you don't yet have any routes defined or if there are certain errors in your metadata

Returns void

validate

lib/index.js:83-85

Will validate the internal json document created by calling compile . This is done using the ajv validator against the official JSON schema. * @throws {Error} Throws an exception if called before compile or initialise .

Examples

var swagger = require ( ' swagger-spec-express ' ) ; var express = require ( ' express ' ) ; var router = new express . Router ( ) ; var os = require ( ' os ' ) ; swagger . swaggerize ( router ) ; router . get ( ' / ' , function ( req , res ) { } ) . describe ( { } ) ; swagger . compile ( ) ; var result = swagger . validate ( ) ; if ( ! result . valid ) { console . warn ( " Compiled Swagger document does not pass validation: " + os . EOL + result . message ) ; }

Returns {valid: boolean, errors: Array<Object>, message: string} The result of the validation

json

lib/index.js:113-117

Returns the swagger specification as a json object.

Examples

var swagger = require ( ' swagger-spec-express ' ) ; var express = require ( ' express ' ) ; var app = express ( ) ; var options = { title : packageJson . title , version : packageJson . version } ; swagger . initialise ( app , options ) ; app . get ( ' /swagger.json ' , function ( err , res ) { res . status ( 200 ) . json ( swagger . json ( ) ) ; } ) . describe ( { responses : { 200 : { description : " Returns the swagger.json document " } } } ) ; swagger . compile ( ) ;

Throws Error Throws an exception if called before compile or initialise . You do not need to call validate first.

Returns Object The Swagger JSON object describing your api. See http://swagger.io/specification/.

addTag

lib/common.js:44-51

Adds a common tag for later use.

Parameters

tag object Allows adding meta data to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag used there. tag.name string Required. The name of the tag. tag.description [string] A short description for the tag. GFM syntax can be used for rich text representation. tag.externalDocs [object] information about external documentation tag.externalDocs.description [string] A short description of the target documentation. GFM syntax can be used for rich text representation. tag.externalDocs.url string Required. The URL for the target documentation. Value MUST be in the format of a URL.

Allows adding meta data to a single tag that is used by the Operation Object. It is not mandatory to have a Tag Object per tag used there. options [AddCommonItemOptions] Options to apply when adding the provided item.

Examples

var swagger = require ( ' swagger-spec-express ' ) ; swagger . common . addTag ( { name : " Info " , description : " Info about the api " } ) ; router . get ( ' / ' , function ( req , res ) { } ) . describe ( { tags : [ " Info " ] , } ) ;

Returns void

addHeaderParameter

lib/common.js:106-114

Adds a common header for later use.

Parameters

header object todo header.format [string] The extending format for the previously mentioned type. See Data Type Formats for further details. header.items [object] Required if type is array . Describes the type of items in the array. header.collectionFormat [string] Determines the format of the array if type array is used. Possible values are:- csv comma separated values foo,bar. ssv space separated values foo bar. tsv tab separated values foo bar. pipes pipe separated values foo|bar. multi corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in query or formData .Default value is csv. header.maximum [number] See json-schema.org. header.exclusiveMaximum [boolean] See json-schema.org. header.minimum [number] See json-schema.org. header.exclusiveMinimum [boolean] See json-schema.org. header.type string Required. The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of string , number , integer , boolean , array or file . If type is file , the consumes MUST be either multipart/form-data , application/x-www-form-urlencoded or both and the parameter MUST be in formData . header.minLength [number] See json-schema.org. header.pattern [string] See json-schema.org. header.maxItems [number] See json-schema.org. header.minItems [number] See json-schema.org. header.uniqueItems [boolean] See json-schema.org. header.multipleOf [number] See json-schema.org. header.description [string] A short description of the header. header.name string The name used to refer to this header at a later stage. header.maxLength [number] See json-schema.org.

todo options [AddCommonItemOptions] Options to apply when adding the provided item.

Examples

var swagger = require ( ' swagger-spec-express ' ) ; swagger . common . parameters . addHeader ( { name : " Originator-Id " , description : " Tells the server where the request originated from " , required : true , type : " string " } ) ; router . get ( ' / ' , function ( req , res ) { } ) . describe ( { common : { parameters : { header : [ " Originator-Id " ] } } } ) ;

Returns void

addBodyParameter

lib/common.js:159-167

Adds a common body parameter for later use.

Parameters

body object The payload that's appended to the HTTP request. Since there can only be one payload, there can only be one body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation. body.description [string] A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed. body.name [string] The name of the parameter. body.in [string] Determines the location of the parameter. body.required [boolean] Determines whether or not this parameter is required or optional. body.schema [object] A deterministic version of a JSON Schema object. body.model [string] The name of the model produced or consumed. body.arrayOfModel [string] The name of the model produced or consumed as an array.

The payload that's appended to the HTTP request. Since there can only be one payload, there can only be one body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation. options [AddCommonItemOptions] Options to apply when adding the provided item.

Examples

var swagger = require ( ' swagger-spec-express ' ) ; swagger . common . parameters . addBody ( { name : " process " , description : " Kicks off the process function on the server at the rest endpoint using the options provided " , required : true , schema : { type : " object " , properties : { " async " : { " type " : " boolean " } } additionalProperties : true } } ) ; router . get ( ' / ' , function ( req , res ) { } ) . describe ( { common : { parameters : { body : [ " process " ] } } } ) ;

Returns void *

addQueryParameter

lib/common.js:225-233

Adds a common query parameter for later use.

Parameters

query object Parameters that are appended to the URL. For example, in /items?id=### , the query parameter is id query.in string Determines the location of the parameter. query.description [string] A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed. query.name string The name of the parameter. query.allowEmptyValue [boolean] allows sending a parameter by name only or with an empty value. query.type string Required. The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of string , number , integer , boolean , array or file . If type is file , the consumes MUST be either multipart/form-data , application/x-www-form-urlencoded or both and the parameter MUST be in formData . query.format [string] The extending format for the previously mentioned type. See Data Type Formats for further details. query.items [object] Required if type is array . Describes the type of items in the array. query.collectionFormat [string] Determines the format of the array if type array is used. Possible values are:- csv comma separated values foo,bar. ssv space separated values foo bar. tsv tab separated values foo bar. pipes pipe separated values foo|bar. multi corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in query or formData .Default value is csv. query.maximum [number] See json-schema.org. query.required [boolean] Determines whether or not this parameter is required or optional. query.minimum [number] See json-schema.org. query.exclusiveMinimum [boolean] See json-schema.org. query.maxLength [number] See json-schema.org. query.minLength [number] See json-schema.org. query.pattern [string] See json-schema.org. query.maxItems [number] See json-schema.org. query.minItems [number] See json-schema.org. query.uniqueItems [boolean] See json-schema.org. query.multipleOf [number] See json-schema.org. query.exclusiveMaximum [boolean] See json-schema.org.

Parameters that are appended to the URL. For example, in , the query parameter is id options [AddCommonItemOptions] Options to apply when adding the provided item.

Examples

var swagger = require ( ' swagger-spec-express ' ) ; swagger . common . parameters . addQuery ( { name : " sort " , description : " The sort order of records e.g. sort=field1,-field2 " , required : false , type : " string " } ) ; router . get ( ' / ' , function ( req , res ) { } ) . describe ( { common : { parameters : { query : [ " sort " ] } } } ) ;

Returns void

addFormDataParameter

lib/common.js:293-301

Adds a common form data parameter for later use.

Parameters

formData object Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded, multipart/form-data or both are used as the content type of the request (in Swagger's definition, the consumes property of an operation). This is the only parameter type that can be used to send files, thus supporting the file type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):- application/x-www-form-urlencoded Similar to the format of Query parameters but as a payload. For example, foo=1&bar=swagger both foo and bar are form parameters. This is normally used for simple parameters that are being transferred. multipart/form-data each parameter takes a section in the payload with an internal header. For example, for the header Content-Disposition: form-data; name="submit-name" the name of the parameter is submit-name. This type of form parameters is more commonly used for file transfers. formData.in string Determines the location of the parameter. formData.description [string] A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed. formData.name string The name of the parameter. formData.allowEmptyValue [boolean] allows sending a parameter by name only or with an empty value. formData.type string Required. The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of string , number , integer , boolean , array or file . If type is file , the consumes MUST be either multipart/form-data , application/x-www-form-urlencoded or both and the parameter MUST be in formData . formData.format [string] The extending format for the previously mentioned type. See Data Type Formats for further details. formData.items [object] Required if type is array . Describes the type of items in the array. formData.collectionFormat [string] Determines the format of the array if type array is used. Possible values are:- csv comma separated values foo,bar. ssv space separated values foo bar. tsv tab separated values foo bar. pipes pipe separated values foo|bar. multi corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in query or formData .Default value is csv. formData.maximum [number] See json-schema.org. formData.required [boolean] Determines whether or not this parameter is required or optional. formData.minimum [number] See json-schema.org. formData.exclusiveMinimum [boolean] See json-schema.org. formData.maxLength [number] See json-schema.org. formData.minLength [number] See json-schema.org. formData.pattern [string] See json-schema.org. formData.maxItems [number] See json-schema.org. formData.minItems [number] See json-schema.org. formData.uniqueItems [boolean] See json-schema.org. formData.multipleOf [number] See json-schema.org. formData.exclusiveMaximum [boolean] See json-schema.org.

Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded, multipart/form-data or both are used as the content type of the request (in Swagger's definition, the consumes property of an operation). This is the only parameter type that can be used to send files, thus supporting the file type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):- application/x-www-form-urlencoded Similar to the format of Query parameters but as a payload. For example, foo=1&bar=swagger both foo and bar are form parameters. This is normally used for simple parameters that are being transferred. options [AddCommonItemOptions] Options to apply when adding the provided item.

Examples

var swagger = require ( ' swagger-spec-express ' ) ; swagger . common . parameters . addFormData ( { name : " csvString " , description : " The csv string to import " , required : true , type : " string " } ) ; router . get ( ' / ' , function ( req , res ) { } ) . describe ( { common : { parameters : { formData : [ " csvString " ] } } } ) ;

Returns void

addPathParameter

lib/common.js:358-366

Adds a common path parameter for later use.

Parameters

path object Used together with Path Templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in /items/{itemId} , the path parameter is itemId. path.in string Determines the location of the parameter. path.description [string] A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed. path.name string The name of the parameter. path.type string Required. The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of string , number , integer , boolean , array or file . If type is file , the consumes MUST be either multipart/form-data , application/x-www-form-urlencoded or both and the parameter MUST be in formData . path.format [string] The extending format for the previously mentioned type. See Data Type Formats for further details. path.items [object] Required if type is array . Describes the type of items in the array. path.collectionFormat [string] Determines the format of the array if type array is used. Possible values are:- csv comma separated values foo,bar. ssv space separated values foo bar. tsv tab separated values foo bar. pipes pipe separated values foo|bar. multi corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in query or formData .Default value is csv. path.maximum [number] See json-schema.org. path.required boolean Determines whether or not this parameter is required or optional. path.minimum [number] See json-schema.org. path.exclusiveMinimum [boolean] See json-schema.org. path.maxLength [number] See json-schema.org. path.minLength [number] See json-schema.org. path.pattern [string] See json-schema.org. path.maxItems [number] See json-schema.org. path.minItems [number] See json-schema.org. path.uniqueItems [boolean] See json-schema.org. path.multipleOf [number] See json-schema.org. path.exclusiveMaximum [boolean] See json-schema.org.

Used together with Path Templating, where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in , the path parameter is itemId. options [AddCommonItemOptions] Options to apply when adding the provided item.

Examples

var swagger = require ( ' swagger-spec-express ' ) ; swagger . common . parameters . addPath ( { name : " entityId " , description : " The id of the entity which contains the data we are using " , required : true , type : " string " } ) ; router . get ( ' /:entityId ' , function ( req , res ) { } ) . describe ( { common : { parameters : { path : [ " entityId " ] } } } ) ;

Returns void

addResponse

lib/common.js:401-408

Adds a common response for later use.

Parameters

response object Describes a single response from an API Operation. response.description string Required. A short description of the response. GFM syntax can be used for rich text representation. response.schema [object] A definition of the response structure. It can be a primitive, an array or an object. If this field does not exist, it means no content is returned as part of the response. As an extension to the Schema Object, its root type value may also be file . This SHOULD be accompanied by a relevant produces mime-type. response.headers [object] A list of headers that are sent with the response. See http://swagger.io/specification/#headersObject response.examples [object] An example of the response message. See http://swagger.io/specification/#exampleObject response.name string The name or http status code used to refer to this response at a later stage. response.model [string] The name of the model produced or consumed. response.arrayOfModel [string] The name of the model produced or consumed as an array.

Describes a single response from an API Operation. options [AddCommonItemOptions] Options to apply when adding the provided item.

Examples

var swagger = require ( ' swagger-spec-express ' ) ; swagger . common . addResponse ( { name : " 500 " , description : " Server Error " , " schema " : { $ref : " #/definitions/serverError " } } ) ; router . get ( ' / ' , function ( req , res ) { } ) . describe ( { common : { responses : [ " 500 " , " 400 " , " 401 " , " 404 " ] , } } ) ;

Returns void

addResponseHeader

lib/common.js:461-469

Adds a common response header for later use.

Parameters

responseHeader object todo responseHeader.format [string] The extending format for the previously mentioned type. See Data Type Formats for further details. responseHeader.items [object] Required if type is array . Describes the type of items in the array. responseHeader.collectionFormat [string] Determines the format of the array if type array is used. Possible values are:- csv comma separated values foo,bar. ssv space separated values foo bar. tsv tab separated values foo bar. pipes pipe separated values foo|bar. multi corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in query or formData .Default value is csv. responseHeader.maximum [number] See json-schema.org. responseHeader.exclusiveMaximum [boolean] See json-schema.org. responseHeader.minimum [number] See json-schema.org. responseHeader.exclusiveMinimum [boolean] See json-schema.org. responseHeader.type string Required. The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of string , number , integer , boolean , array or file . If type is file , the consumes MUST be either multipart/form-data , application/x-www-form-urlencoded or both and the parameter MUST be in formData . responseHeader.minLength [number] See json-schema.org. responseHeader.pattern [string] See json-schema.org. responseHeader.maxItems [number] See json-schema.org. responseHeader.minItems [number] See json-schema.org. responseHeader.uniqueItems [boolean] See json-schema.org. responseHeader.multipleOf [number] See json-schema.org. responseHeader.description [string] A short description of the header. responseHeader.name string The name used to refer to this header at a later stage. responseHeader.maxLength [number] See json-schema.org.

todo options [AddCommonItemOptions] Options to apply when adding the provided item.

Examples

var swagger = require ( ' swagger-spec-express ' ) ; swagger . common . addResponseHeader ( { name : " Response-Id " , description : " A unique response id for tracking in logs " , type : " string " } ) ; router . get ( ' / ' , function ( req , res ) { } ) . describe ( { responses : { " 200 " : { commonHeaders : [ " Response-Id " ] } } } ) ;

Returns void

addModel

lib/common.js:499-527

Adds a common model for later use.

Parameters

model object The schema for the model object to add. Should be a valid Schema object.

The schema for the model object to add. Should be a valid Schema object. inputOptions [AddCommonItemOptions] Options to apply when adding the provided item.

Examples

var swagger = require ( ' swagger-spec-express ' ) ; swagger . common . addModel ( { " name " : " serverError " , " type " : " object " , " properties " : { " message " : { " type " : " string " } } } ) ; router . get ( ' / ' , function ( req , res ) { } ) . describe ( { responses : { " 500 " : { model : " serverError " } } } ) ;

Returns void

AddCommonItemOptions

lib/common.js:554-558

Parameters

validation string Controls how validation works, can either be warn (Sends message to console.warn), throw (Throws an Error) or ignore .

Controls how validation works, can either be (Sends message to console.warn), (Throws an Error) or . deleteNameFromCommon Controls if, after adding the item to common, it should remove the name in order to pass the Swagger schema validation.

Reporting Bugs & Issues

Log them on GitHub

Contributing

If you would like to help contribute to the library, fork it and submit a pull request.

Leveraging this module to validate the data returned from your integration tests

todo

Awesome code reuse

todo

Roadmap

Low

Currently populating rootDocument.responses but then injecting the responses directly into the operation. Should use the $ref

Currently populating rootDocument.parameters but then injecting the responses directly into the operation. Should use the $ref

Medium

Ability to describe the app like a router (alternate to passing all the data into the init method).

More tests

High