Skip to content

Latest commit

 

History

History
810 lines (592 loc) · 45.4 KB

API.md

File metadata and controls

810 lines (592 loc) · 45.4 KB
Raw

sway

A library that simplifies OpenAPI integrations.

sway.ApiDefinition

Kind: static 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)
customFormatGenerators object The key/value pair of custom format generators (The keys are the format name and the values are functions. See json-schema-mocker Custom Format)
customValidators Array.<DocumentValidationFunction> The array of custom validators
definition object The original OpenAPI definition
definitionRemotesResolved object The OpenAPI 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 OpenAPI 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 OpenAPI 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 OpenAPI version

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

The OpenAPI Definition object.

Note: Do not use directly.

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

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

apiDefinition.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 ApiDefinition
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 OpenAPI operation id, path string or the http client request (or equivalent)
[method] string The OpenAPI operation method (not used when providing an operation id)

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

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

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

Param Type Description
[path] string The OpenAPI path

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

Returns all operations for the provided tag.

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

Param Type Description
[tag] string The OpenAPI tag

apiDefinition.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 ApiDefinition
Returns: Path - The corresponding Path object for the requested path or request

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

apiDefinition.getPaths() ⇒ Array.<Path>

Returns all path objects for the OpenAPI definition.

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

apiDefinition.registerFormat(name, validator)

Registers a custom format.

Kind: instance method of ApiDefinition

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

apiDefinition.registerFormatGenerator(name, formatGenerator)

Registers a custom format generator.

Kind: instance method of ApiDefinition

Param Type Description
name string The name of the format
formatGenerator function The format generator (See json-schema-mocker Custom Format)

apiDefinition.registerValidator(validator)

Registers a custom validator.

Kind: instance method of ApiDefinition
Throws:

  • TypeError If the validator is not a function
Param Type Description
validator DocumentValidationFunction The validator

apiDefinition.unregisterFormat(name)

Unregisters a custom format.

Kind: instance method of ApiDefinition

Param Type Description
name string The name of the format

apiDefinition.unregisterFormatGenerator(name)

Unregisters a custom format generator.

Kind: instance method of ApiDefinition

Param Type Description
name string The name of the format generator

apiDefinition.validate() ⇒ ValidationResults

Performs validation of the OpenAPI definition.

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

sway.CreateOptions : object

Options used when creating the ApiDefinition.

Kind: static typedef of sway
Properties

Name Type Description
definition object | string The OpenAPI definition location or structure
jsonRefs object (See JsonRefs~JsonRefsOptions)
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)
customFormatGenerators object The key/value pair of custom format generators (The keys are the format name and the values are functions. See json-schema-mocker Custom Format)
customValidators Array.<DocumentValidationFunction> The custom validators

sway.DocumentValidationFunction ⇒ ValidationResults

Function used for custom validation of OpenAPI documents

Kind: static typedef of sway
Returns: ValidationResults - The validation results

Param Type Description
apiDefinition ApiDefinition The ApiDefinition object

sway.Operation

Kind: static 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 OpenAPI Operation object.

Note: Do not use directly.

Extra Properties: Other than the documented properties, this object also exposes all properties of the OpenAPI Operation 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, [options]) ⇒ 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)
[options] RequestValidationOptions The validation options

operation.validateResponse(res, [options]) ⇒ 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
[options] ResponseValidationOptions The validation options

sway.Parameter

Kind: static 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 OpenAPI Parameter object.

Note: Do not use directly.

Extra Properties: Other than the documented properties, this object also exposes all properties of the OpenAPI Parameter 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: static 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: static class of sway
Properties

Name Type Description
apiDefinition ApiDefinition The ApiDefinition 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(apiDefinition, 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 OpenAPI Path Object.

Param Type Description
apiDefinition ApiDefinition The ApiDefinition 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.RequestValidationFunction ⇒ ValidationResults

Request validation function.

Kind: static typedef of sway
Returns: ValidationResults - The validation results

Param Type Description
res ServerResponseWrapper The response or response like object
def Response The Response definition (useful primarily when calling Operation#validateResponse as Response#validateResponse the caller should have access to the Response object already.)

sway.RequestValidationOptions : object

Request validation options.

Kind: static typedef of sway
Properties

Name Type Default Description
strictMode boolean | object false Enablement of strict mode validation. If strictMode is a boolean and is true, all form fields, headers and query parameters must be defined in the OpenAPI document for this operation. If strictMode is an object, the keys correspond to the in property values of the OpenAPI Parameter Object and its value is a boolean that when true turns on strict mode validation for the request location matching the key. Valid keys are formData, header and query. (body and path are not necessary since body strict mode is possible via its schema and path is always required.)
customValidators RequestValidationFunction The custom validators

sway.Response

Kind: static 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 OpenAPI Response object.

Note: Do not use directly.

Extra Properties: Other than the documented properties, this object also exposes all properties of the OpenAPI Response 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, [options]) ⇒ 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
[options] ResponseValidationOptions The validation options

sway.ResponseValidationFunction ⇒ ValidationResults

Response validation function.

Kind: static typedef of sway
Returns: ValidationResults - The validation results

Param Type Description
req object The http client request (or equivalent)
op Operation The Operation object for the request

sway.ResponseValidationOptions : object

Response validation options.

Kind: static typedef of sway
Properties

Name Type Default Description
strictMode boolean | object false Enablement of strict mode validation. If strictMode is a boolean and is true, all form fields, headers and query parameters must be defined in the OpenAPI definition for this operation. If strictMode is an object, the keys correspond to the in property values of the OpenAPI Parameter Object and its value is a boolean that when true turns on strict mode validation for the request location matching the key. Valid keys are header. (body, query and path are not necessary since body strict mode is possible via its schema and path, query do not matter for responses.)
customValidators RequestValidationFunction The custom validators

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: static 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.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: static 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: static typedef of sway
Properties

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

sway.create(options) ⇒ Promise.<ApiDefinition>

Creates an ApiDefinition object from the provided OpenAPI definition.

Kind: static method of sway
Returns: Promise.<ApiDefinition> - The promise

Param Type Description
options CreateOptions The options for loading the definition(s)

Example

Sway.create({
  definition: 'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml'
})
.then(function (apiDefinition) {
  console.log('Documentation URL: ', apiDefinition.documentationUrl);
}, function (err) {
  console.error(err.stack);
});