sway/docs/API.md

Sway

A library for simpler Swagger integrations.

• Sway
  • inner
    • ~Operation
      • new Operation(pathObject, method, definition, definitionFullyResolved, pathToDefinition)
      • .getParameter(name, [location]) ⇒ Parameter
      • .getParameters() ⇒ Array.<Parameter>
      • .getResponse([statusCode]) ⇒ Response
      • .getResponses() ⇒ Array.<Response>
      • .getSecurity() ⇒ Array.<object>
      • .validateRequest(req) ⇒ ValidationResults
      • .validateResponse(res) ⇒ ValidationResults
    • ~Parameter
      • new Parameter(opOrPathObject, definition, definitionFullyResolved, pathToDefinition)
      • .getSample() ⇒ *
      • .getValue(req) ⇒ ParameterValue
    • ~ParameterValue
      • new ParameterValue(parameterObject, raw)
    • ~Path
      • new Path(api, path, definition, definitionFullyResolved, pathToDefinition, isCaseSensitive)
      • .getOperation(idOrMethod) ⇒ Array.<Operation>
      • .getOperations() ⇒ Array.<Operation>
      • .getOperationsByTag(tag) ⇒ Array.<Operation>
      • .getParameters() ⇒ Array.<Parameter>
    • ~Response
      • new Response(operationObject, statusCode, definition, definitionFullyResolved, pathToDefinition)
      • .getExample([mimeType]) ⇒ string
      • .getSample() ⇒ *
      • .validateResponse(res) ⇒ ValidationResults
    • ~ServerResponseWrapper : object
    • ~SwaggerApi
      • new SwaggerApi(definition, definitionRemotesResolved, definitionFullyResolved, references, options)
      • .getOperation(idOrPathOrReq, [method]) ⇒ Operation
      • .getOperations([path]) ⇒ Array.<Operation>
      • .getOperationsByTag([tag]) ⇒ Array.<Operation>
      • .getPath(pathOrReq) ⇒ Path
      • .getPaths() ⇒ Array.<Path>
      • .registerFormat(name, validator)
      • .registerValidator(validator)
      • .validate() ⇒ ValidationResults
    • ~ValidationEntry : object
    • ~ValidationResults : object
    • ~ValidatorCallback ⇒ ValidationResults
    • ~buildRegex(hostTemplate, basePathPrefix, path, isCaseSensitive) ⇒ object
  • static
    • .create(options) ⇒ Promise

Sway~Operation

Kind: inner class of Sway
Properties

Name	Type	Description
definition	object	The operation definition (The raw operation definition after remote references were resolved)
definitionFullyResolved	object	The operation definition with all of its resolvable references resolved
method	string	The HTTP method for this operation
pathObject	Path	The Path object
pathToDefinition	Array.<string>	The path segments to the operation definition
parameterObjects	Array.<Parameter>	The Parameter objects
ptr	string	The JSON Pointer to the operation
securityDefinitions	object	The security definitions used by this operation

• ~Operation
  • new Operation(pathObject, method, definition, definitionFullyResolved, pathToDefinition)
  • .getParameter(name, [location]) ⇒ Parameter
  • .getParameters() ⇒ Array.<Parameter>
  • .getResponse([statusCode]) ⇒ Response
  • .getResponses() ⇒ Array.<Response>
  • .getSecurity() ⇒ Array.<object>
  • .validateRequest(req) ⇒ ValidationResults
  • .validateResponse(res) ⇒ ValidationResults

new Operation(pathObject, method, definition, definitionFullyResolved, pathToDefinition)

The Swagger Operation object.

Note: Do not use directly.

Extra Properties: Other than the documented properties, this object also exposes all properties of the definition object.

Param	Type	Description
pathObject	Path	The Path object
method	string	The operation method
definition	object	The operation definition (The raw operation definition after remote references were resolved)
definitionFullyResolved	object	The operation definition with all of its resolvable references resolved
pathToDefinition	Array.<string>	The path segments to the operation definition

operation.getParameter(name, [location]) ⇒ Parameter

Returns the parameter with the provided name and location when provided.

Kind: instance method of Operation
Returns: Parameter - The Parameter matching the location and name combination or undefined if there is no match

Param	Type	Description
name	string	The name of the parameter
[location]	string	The location (in) of the parameter (Used for disambiguation)

operation.getParameters() ⇒ Array.<Parameter>

Returns all parameters for the operation.

Kind: instance method of Operation
Returns: Array.<Parameter> - All Parameter objects for the operation

operation.getResponse([statusCode]) ⇒ Response

Returns the response for the requested status code or the default response (if available) if none is provided.

Kind: instance method of Operation
Returns: Response - The Response or undefined if one cannot be found

Param	Type	Default	Description
[statusCode]	number | string	'default'	The status code

operation.getResponses() ⇒ Array.<Response>

Returns all responses for the operation.

Kind: instance method of Operation
Returns: Array.<Response> - All Response objects for the operation

operation.getSecurity() ⇒ Array.<object>

Returns the composite security definitions for this operation.

The difference between this API and this.security is that this.security is the raw security value for the operation where as this API will return the global security value when available and this operation's security is undefined.

Kind: instance method of Operation
Returns: Array.<object> - The security for this operation

operation.validateRequest(req) ⇒ ValidationResults

Validates the request.

Note: Below is the list of req properties used (req should be an http.ClientRequest or equivalent):

• body: Used for body and formData parameters
• files: Used for formData parameters whose type is file
• headers: Used for header parameters and consumes
• originalUrl: used for path parameters
• query: Used for query parameters
• url: used for path parameters

For path parameters, we will use the operation's regexp property to parse out path parameters using the originalUrl or url property.

(See: https://nodejs.org/api/http.html#http_class_http_clientrequest)

Kind: instance method of Operation
Returns: ValidationResults - The validation results

Param	Type	Description
req	object	The http client request (or equivalent)

operation.validateResponse(res) ⇒ ValidationResults

Validates the response.

Kind: instance method of Operation
Returns: ValidationResults - The validation results

Param	Type	Description
res	ServerResponseWrapper	The response or response like object

Sway~Parameter

Kind: inner class of Sway
Properties

Name	Type	Description
definition	object	The parameter definition (The raw parameter definition after remote references were resolved)
definitionFullyResolved	object	The parameter definition with all of its resolvable references resolved
operationObject	Operation	The Operation object the parameter belongs to (Can be undefined for path-level parameters)
pathObject	Path	The Path object the parameter belongs to
pathToDefinition	Array.<string>	The path segments to the parameter definition
ptr	string	The JSON Pointer to the parameter definition
schema	object	The JSON Schema for the parameter (For non-body parameters, this is a computed value)

• ~Parameter
  • new Parameter(opOrPathObject, definition, definitionFullyResolved, pathToDefinition)
  • .getSample() ⇒ *
  • .getValue(req) ⇒ ParameterValue

new Parameter(opOrPathObject, definition, definitionFullyResolved, pathToDefinition)

The Swagger Parameter object.

Note: Do not use directly.

Extra Properties: Other than the documented properties, this object also exposes all properties of the definition object.

Param	Type	Description
opOrPathObject	Operation | Path	The Operation or Path object
definition	object	The parameter definition (The raw parameter definition after remote references were resolved)
definitionFullyResolved	object	The parameter definition with all of its resolvable references resolved
pathToDefinition	Array.<string>	The path segments to the parameter definition

parameter.getSample() ⇒ *

Returns a sample value for the parameter based on its schema;

Kind: instance method of Parameter
Returns: * - The sample value

parameter.getValue(req) ⇒ ParameterValue

Returns the parameter value from the request.

Note: Below is the list of req properties used (req should be an http.ClientRequest or equivalent):

• body: Used for body and formData parameters
• files: Used for formData parameters whose type is file
• headers: Used for header parameters
• originalUrl: used for path parameters
• query: Used for query parameters
• url: used for path parameters

For path parameters, we will use the operation's regexp property to parse out path parameters using the originalUrl or url property.

(See: https://nodejs.org/api/http.html#http_class_http_clientrequest)

Kind: instance method of Parameter
Returns: ParameterValue - The parameter value object
Throws:

• Error If the in value of the parameter's schema is not valid or if the req property to retrieve the parameter is missing

Param	Type	Description
req	object	The http client request (or equivalent)

Sway~ParameterValue

Kind: inner class of Sway
Properties

Name	Type	Description
error	Error	The error(s) encountered during processing/validating the parameter value
parameterObject	Parameter	The Parameter object
raw	*	The original parameter value (Does not take default values into account)
valid	boolean	Whether or not this parameter is valid based on its JSON Schema
value	*	The processed value (Takes default values into account and does type coercion when necessary and possible). This can the original value in the event that processing the value is impossible (missing schema type) or undefined if processing the value failed (invalid types, etc.).

new ParameterValue(parameterObject, raw)

Object representing a parameter value.

Note: Do not use directly.

Param	Type	Description
parameterObject	Parameter	The Parameter object
raw	*	The original/raw value

Sway~Path

Kind: inner class of Sway
Properties

Name	Type	Description
api	SwaggerApi	The SwaggerApi object
definition	object	The path definition (The raw path definition after remote references were resolved)
definitionFullyResolved	object	The path definition with all of its resolvable references resolved
operationObjects	Array.<Operation>	The Operation objects
parameterObjects	Array.<Parameter>	The path-level Parameter objects
path	string	The path string
pathToDefinition	Array.<string>	The path segments to the path definition
ptr	ptr	The JSON Pointer to the path
regexp	regexp	The RegExp used to match request paths against this path

• ~Path
  • new Path(api, path, definition, definitionFullyResolved, pathToDefinition, isCaseSensitive)
  • .getOperation(idOrMethod) ⇒ Array.<Operation>
  • .getOperations() ⇒ Array.<Operation>
  • .getOperationsByTag(tag) ⇒ Array.<Operation>
  • .getParameters() ⇒ Array.<Parameter>

new Path(api, path, definition, definitionFullyResolved, pathToDefinition, isCaseSensitive)

The Path object.

Note: Do not use directly.

Extra Properties: Other than the documented properties, this object also exposes all properties of the definition object.

Param	Type	Description
api	SwaggerApi	The SwaggerApi object
path	string	The path string
definition	object	The path definition (The raw path definition after remote references were resolved)
definitionFullyResolved	object	The path definition with all of its resolvable references resolved
pathToDefinition	Array.<string>	The path segments to the path definition
isCaseSensitive	Array.<string>	Specifies if to consider the path case sensitive or not

path.getOperation(idOrMethod) ⇒ Array.<Operation>

Return the operation for this path and operation id or method.

Kind: instance method of Path
Returns: Array.<Operation> - The Operation objects for this path and method or undefined if there is no operation for the provided method

Param	Type	Description
idOrMethod	string	The operation id or method

path.getOperations() ⇒ Array.<Operation>

Return the operations for this path.

Kind: instance method of Path
Returns: Array.<Operation> - The Operation objects for this path

path.getOperationsByTag(tag) ⇒ Array.<Operation>

Return the operations for this path and tag.

Kind: instance method of Path
Returns: Array.<Operation> - The Operation objects for this path and tag

Param	Type	Description
tag	string	The tag

path.getParameters() ⇒ Array.<Parameter>

Return the parameters for this path.

Kind: instance method of Path
Returns: Array.<Parameter> - The Parameter objects for this path

Sway~Response

Kind: inner class of Sway
Properties

Name	Type	Description
definition	object	The response definition (The raw responsedefinition after remote references were resolved)
definitionFullyResolved	object	The response definition with all of its resolvable references resolved
operationObject	Operation	The Operation object
pathToDefinition	Array.<string>	The path segments to the path definition
ptr	string	The JSON Pointer to the response definition
statusCode	string	The status code

• ~Response
  • new Response(operationObject, statusCode, definition, definitionFullyResolved, pathToDefinition)
  • .getExample([mimeType]) ⇒ string
  • .getSample() ⇒ *
  • .validateResponse(res) ⇒ ValidationResults

new Response(operationObject, statusCode, definition, definitionFullyResolved, pathToDefinition)

The Swagger Response object.

Note: Do not use directly.

Extra Properties: Other than the documented properties, this object also exposes all properties of the definition object.

Param	Type	Description
operationObject	Operation	The Operation object
statusCode	string	The status code
definition	object	The response definition (The raw response definition after remote references were resolved)
definitionFullyResolved	object	The response definition with all of its resolvable references resolved
pathToDefinition	Array.<string>	The path segments to the path definition

response.getExample([mimeType]) ⇒ string

Returns the response example for the mime-type.

Kind: instance method of Response
Returns: string - The response example as a string or undefined if the response code and/or mime-type is missing

Param	Type	Description
[mimeType]	string	The mime type

response.getSample() ⇒ *

Returns a sample value.

Kind: instance method of Response
Returns: * - The sample value for the response, which can be undefined if the response schema is not provided

response.validateResponse(res) ⇒ ValidationResults

Validates the response.

Kind: instance method of Response
Returns: ValidationResults - The validation results

Param	Type	Description
res	ServerResponseWrapper	The response or response like object

Sway~ServerResponseWrapper : object

Server response wrapper.

Since the low level http.ServerResponse object is not always guaranteed and even if it is, there is no public way to gather the necessary parts of the response to perform validation, this object encapsulates the required response information to perform response validation.

Kind: inner typedef of Sway
Properties

Name	Type	Default	Description
body	*		The response body
encoding	string		The encoding of the body when the body is a Buffer
headers	object		The response headers
statusCode	number | string	default	The response status code

Sway~SwaggerApi

Kind: inner class of Sway
Properties

Name	Type	Description
customFormats	object	The key/value pair of custom formats (The keys are the format name and the values are async functions. See ZSchema Custom Formats)
customValidators	Array.<ValidatorCallback>	The array of custom validators
definition	object	The original Swagger definition
definitionRemotesResolved	object	The Swagger definition with only its remote references resolved (This means all references to external/remote documents are replaced with its dereferenced value but all local references are left unresolved.)
definitionFullyResolved	object	The Swagger definition with all of its resolvable references resolved (This means that all resolvable references are replaced with their dereferenced value.)
documentationUrl	string	The URL to the Swagger documentation
pathObjects	Array.<Path>	The unique Path objects
options	object	The options passed to the constructor
references	object	The reference metadata (See JsonRefs~ResolvedRefDetails)
version	string	The Swagger API version

• ~SwaggerApi
  • new SwaggerApi(definition, definitionRemotesResolved, definitionFullyResolved, references, options)
  • .getOperation(idOrPathOrReq, [method]) ⇒ Operation
  • .getOperations([path]) ⇒ Array.<Operation>
  • .getOperationsByTag([tag]) ⇒ Array.<Operation>
  • .getPath(pathOrReq) ⇒ Path
  • .getPaths() ⇒ Array.<Path>
  • .registerFormat(name, validator)
  • .registerValidator(validator)
  • .validate() ⇒ ValidationResults

new SwaggerApi(definition, definitionRemotesResolved, definitionFullyResolved, references, options)

The Swagger API object.

Note: Do not use directly.

Extra Properties: Other than the documented properties, this object also exposes all properties of the definition object.

Param	Type	Description
definition	object	The original Swagger definition
definitionRemotesResolved	object	The Swagger definition with all of its remote references resolved
definitionFullyResolved	object	The Swagger definition with all of its references resolved
references	object	The location and resolution of the resolved references in the Swagger definition
options	object	The options passed to swaggerApi.create

swaggerApi.getOperation(idOrPathOrReq, [method]) ⇒ Operation

Returns the operation for the given path and operation.

Note: Below is the list of properties used when reqOrPath is an http.ClientRequest (or equivalent):

• method
• originalUrl
• url

(See: https://nodejs.org/api/http.html#http_class_http_clientrequest)

Kind: instance method of SwaggerApi
Returns: Operation - The Operation for the provided operation id, or path and method or undefined if there is no operation for that operation id, or path and method combination

Param	Type	Description
idOrPathOrReq	string | object	The Swagger opeartion id, path string or the http client request (or equivalent)
[method]	string	The Swagger operation method (not used when providing an operation id)

swaggerApi.getOperations([path]) ⇒ Array.<Operation>

Returns all operations for the provided path or all operations in the API.

Kind: instance method of SwaggerApi
Returns: Array.<Operation> - All Operation objects for the provided path or all API operations

Param	Type	Description
[path]	string	The Swagger path

swaggerApi.getOperationsByTag([tag]) ⇒ Array.<Operation>

Returns all operations for the provided tag.

Kind: instance method of SwaggerApi
Returns: Array.<Operation> - All Operation objects for the provided tag

Param	Type	Description
[tag]	string	The Swagger tag

swaggerApi.getPath(pathOrReq) ⇒ Path

Returns the path object for the given path or request.

Note: Below is the list of properties used when reqOrPath is an http.ClientRequest (or equivalent):

• originalUrl
• url

(See: https://nodejs.org/api/http.html#http_class_http_clientrequest)

Kind: instance method of SwaggerApi
Returns: Path - The corresponding Path object for the requested path or request

Param	Type	Description
pathOrReq	string | object	The Swagger path string or the http client request (or equivalent)

swaggerApi.getPaths() ⇒ Array.<Path>

Returns all path objects for the Swagger API.

Kind: instance method of SwaggerApi
Returns: Array.<Path> - The Path objects

swaggerApi.registerFormat(name, validator)

Registers a custom format.

Kind: instance method of SwaggerApi

Param	Type	Description
name	string	The name of the format
validator	function	The format validator (See ZSchema Custom Format)

swaggerApi.registerValidator(validator)

Registers a custom validator.

Kind: instance method of SwaggerApi
Throws:

• TypeError If the validator is not a function

Param	Type	Description
validator	ValidatorCallback	The validator

swaggerApi.validate() ⇒ ValidationResults

Performs validation of the Swagger API document(s).

Kind: instance method of SwaggerApi
Returns: ValidationResults - The validation results

Sway~ValidationEntry : object

Validation error/warning object.

When this object is created as a result of JSON Schema validation, this object is created by z-schema and it owns the structure so there can be extra properties not documented below.

Kind: inner typedef of Sway
Properties

Name	Type	Description
code	string	The code used to identify the error/warning
error	string	Whenever there is an upstream Error encountered, its message is here
errors	Array.<ValidationEntry>	The nested error(s) encountered during validation
lineage	Array.<string>	Contains the composition lineage for circular composition errors
message	string	The human readable description of the error/warning
name	string	The header name for header validation errors
params	array	The parameters used when validation failed (This is a z-schema construct and is only set for JSON Schema validation errors.)
path	Array.<string>	The path to the location in the document where the error/warning occurred
schemaId	string	The schema id *(This is a z-schema construct and is only set for JSON Schema validation errors and when its value is not undefined.)

Sway~ValidationResults : object

Validation results object.

Kind: inner typedef of Sway
Properties

Name	Type	Description
errors	Array.<ValidationEntry>	The validation errors
warnings	Array.<ValidationEntry>	The validation warnings

Sway~ValidatorCallback ⇒ ValidationResults

Callback used for validation.

Kind: inner typedef of Sway
Returns: ValidationResults - The validation results

Param	Type	Description
api	SwaggerApi	The Swagger API object

Sway~buildRegex(hostTemplate, basePathPrefix, path, isCaseSensitive) ⇒ object

Builds the regex required for matching the request url against the templated path in the swagger spec.

Kind: inner method of Sway
Returns: object - The pathToRegexp object

Param	Type	Description
hostTemplate	srting	the host template if any or empty string
basePathPrefix	string	the basePathPrefix if any or '/'
path	string	the templated path
isCaseSensitive	bool	specifies if to use case sensitive comparison or not

Sway.create(options) ⇒ Promise

Creates a SwaggerApi object from its Swagger definition(s).

Kind: static method of Sway
Returns: Promise - The promise

Param	Type	Description
options	object	The options for loading the definition(s)
options.definition	object | string	The Swagger definition location or structure
[options.jsonRefs]	object	(See JsonRefs~JsonRefsOptions)
[options.customValidators]	Array.<ValidatorCallback>	The custom validators

Example

SwaggerApi.create({definition: 'http://petstore.swagger.io/v2/swagger.yaml'})
  .then(function (api) {
    console.log('Documentation URL: ', api.documentationUrl);
  }, function (err) {
    console.error(err.stack);
  });