Skip to content

Latest commit

 

History

History
675 lines (493 loc) · 36.9 KB

API.md

File metadata and controls

675 lines (493 loc) · 36.9 KB
Raw

Sway

A library for simpler Swagger integrations.

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

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
  • 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 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)

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
  • 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 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

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

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

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

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
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

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
  • 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):

  • 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.registerValidator(validator)

Registers a 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.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);
  });