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.
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.
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"
}
}
});
Simply follow the instructions for the official Swagger UI project. or use your favourite, alternative Swagger UI theme.
- Core:
- Initialise
- Swaggerise
- Describe
- Compile
- Validate
- Json
- Adding common items:
- Add Tag
- Add Header Parameter
- Add Body Parameter
- Add Query Parameter
- Add Form Data Parameter
- Add Path Parameter
- Add Response
- Add Response Header
- Add Model
- Add Common Item Options
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
app
object The express app class that you want to describe using swaggeroptions.externalDocs.url
string Required. The URL for the target documentation. Value MUST be in the format of a URL.options.document
[object] An existing or manually created swagger document to use as a base document and expanded upon. Note that the other options will override the base items in this supplied document. See http://swagger.io/specification/ for info on how to manually construct a document.options.title
[string] The title of the application.options.description
[string] A short description of the application. GFM syntax can be used for rich text representation.options.termsOfService
[string] The Terms of Service for the API.options.contact
[object] The contact information for the exposed API. See Contact Object.options.contact.name
[string] The identifying name of the contact person/organization.options.contact.url
[string] The URL pointing to the contact information. MUST be in the format of a URL.options.contact.email
[string] The email address of the contact person/organization. MUST be in the format of an email address.
options.license
[object] The license information for the exposed API. See License Object.options.version
[string] Provides the version of the application API.options.host
[string] The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the host is not included, the host serving the documentation is to be used (including the port). The host does not support Path Templating.options.basePath
[string] The base path on which the API is served, which is relative to the host. If it is not included, the API is served directly under the host. The value MUST start with a leading slash (/). The basePath does not support Path Templating. (optional, default/
)options.schemes
[Array<string>] The transfer protocol of the API. Values MUST be from the list: "http", "https", "ws", "wss". If the schemes is not included, the default scheme to be used is the one used to access the Swagger definition itself.options
object The options object, used to control how the swagger document will be generatedoptions.produces
[Array<string>] A list of MIME types the APIs can produce. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under Mime Types.options.paths
[object] The available paths and operations for the API. See Paths Object.options.definitions
[object] An object to hold data types produced and consumed by operations. See Definitions Object.options.parameters
[object] 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.options.responses
[object] An object to hold responses that can be used across operations. This property does not define global responses for all operations. See Response Definitions Object.options.securityDefinitions
[object] Security scheme definitions that can be used across the specification. See Security Definitions Object.options.security
[object] 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.options.defaultSecurity
[(string | Array<string>)] The default security schema to use on a route when the security parameter is set to true. Must be a single Security Requirement Object.options.tags
[object] 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.options.externalDocs
[object] Additional external documentation. See External Documentation Object.options.externalDocs.description
[string] A short description of the target documentation. GFM syntax can be used for rich text representation.
options.consumes
[Array<string>] A list of MIME types the APIs can consume. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under Mime Types.
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: {
// An existing swagger json spec file that you may want to build on
},
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: {
//manual paths here if desired, not required.
},
definitions: {
//manual definitions here if desired, not required.
},
parameters: {
//manual definitions here if desired, not required.
},
responses: {
//manual responses here if desired, not required.
},
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
- Throws Error if no app object provided
- Throws Error if no options object provided
Returns void
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
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 documentationmetaData.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.addResponsemetaData.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.addHeadermetaData.common.parameters.body
[Array<string>] A common body parameter as added by calling common.parameters.addBodymetaData.common.parameters.query
[Array<string>] A common query string parameter as added by calling common.parameters.addQuerymetaData.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.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
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
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
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
orinitialise
. You do not need to callvalidate
first.
Returns Object The Swagger JSON object describing your api. See http://swagger.io/specification/.
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.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
Adds a common header for later use.
Parameters
header
object todoheader.format
[string] The extending format for the previously mentioned type. See Data Type Formats for further details.header.items
[object] Required if type isarray
. 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
orformData
.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 ofstring
,number
,integer
,boolean
,array
orfile
. If type isfile
, the consumes MUST be eithermultipart/form-data
,application/x-www-form-urlencoded
or both and the parameter MUST be informData
.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.
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
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.
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,
type: "object",
schema : {
type: "object",
properties: {
"async": {
"type": "boolean"
}
}
additionalProperties: true
}
});
//...
router.get('/', function (req, res) {
//...
}).describe({
//...
common: {
//...
parameters: {
body: ["process"]
}
//...
}
//...
});
Returns void *
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 idquery.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 ofstring
,number
,integer
,boolean
,array
orfile
. If type isfile
, the consumes MUST be eithermultipart/form-data
,application/x-www-form-urlencoded
or both and the parameter MUST be informData
.query.format
[string] The extending format for the previously mentioned type. See Data Type Formats for further details.query.items
[object] Required if type isarray
. 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
orformData
.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.
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
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 ofstring
,number
,integer
,boolean
,array
orfile
. If type isfile
, the consumes MUST be eithermultipart/form-data
,application/x-www-form-urlencoded
or both and the parameter MUST be informData
.formData.format
[string] The extending format for the previously mentioned type. See Data Type Formats for further details.formData.items
[object] Required if type isarray
. 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
orformData
.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.
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
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 ofstring
,number
,integer
,boolean
,array
orfile
. If type isfile
, the consumes MUST be eithermultipart/form-data
,application/x-www-form-urlencoded
or both and the parameter MUST be informData
.path.format
[string] The extending format for the previously mentioned type. See Data Type Formats for further details.path.items
[object] Required if type isarray
. 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
orformData
.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.
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
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 befile
. 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/#headersObjectresponse.examples
[object] An example of the response message. See http://swagger.io/specification/#exampleObjectresponse.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.
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
Adds a common response header for later use.
Parameters
responseHeader
object todoresponseHeader.format
[string] The extending format for the previously mentioned type. See Data Type Formats for further details.responseHeader.items
[object] Required if type isarray
. 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
orformData
.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 ofstring
,number
,integer
,boolean
,array
orfile
. If type isfile
, the consumes MUST be eithermultipart/form-data
,application/x-www-form-urlencoded
or both and the parameter MUST be informData
.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.
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
Adds a common model for later use.
Parameters
model
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
Parameters
validation
string Controls how validation works, can either bewarn
(Sends message to console.warn),throw
(Throws an Error) orignore
.deleteNameFromCommon
Controls if, after adding the item to common, it should remove the name in order to pass the Swagger schema validation.
Log them on GitHub
If you would like to help contribute to the library, fork it and submit a pull request.
todo
todo
- 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
- Ability to describe the app like a router (alternate to passing all the data into the init method).
- More tests
- addResponse should look for model & arrayOfModel
- Better error messages in general so you don't need to debug
- Ability to inject certain things into parameters. E.g. many GET routes will have GET /thing/:identifier would be nice to inject the name in there
- when using arrayOfModel the schema doesn't have an id, so makes it harder to use ajv. Currently we just wrapping in {items:}. Still an issue?
- proper error classes for specific errors to allow filtering and handling