@mimik/swagger-helper

swagger-helper

Example

import swaggerHelper from '@mimik/swagger-helper';

Example

import { TOKEN_PARAMS, getAPIFile, rejectRequest, convertParams } from '@mimik/swagger-helper';

• swagger-helper
  • async
    • ~getAPIFile(apiFilename, correlationId, options) ⇒ Promise.<object>
  • sync
    • ~rejectRequest(error, context, res, logLevel, parameters) ⇒ void
    • ~convertParams(context, logLevel) ⇒ object

swagger-helper~getAPIFile(apiFilename, correlationId, options) ⇒ Promise.<object>

Gets the API file from bitbucket or swaggerhub and stores it in the given PATH location.

Kind: inner method of swagger-helper
Returns: Promise.<object> - The API file itself.
Category: async
Throws:

• Error An error is thrown if the apiFilename resolution generates an error or the request to the API provider fails or the file cannot be saved.

The request to the API provider is made through rpRetry (@mimik/request-retry), which implements the timeout and retry mechanism for the API call.

apiInfo options has the following format:

{
   "provider": "provider of the api file, can be `swaggerhub` or `bitbucket`, defaults to `bitbucket` when omitted",
   "bitbucket": {
     "username": "username for bitbucket",
     "password": "password for bitbucket"
   },
   "swaggerhub": "apiKey for accessing private API on swaggerhub, can be optional if the API is accessible publicly"
}

Requires: module:@mimik/request-retry, module:@mimik/sumologic-winston-logger, module:fs, module:js-yaml, module:path

Param	Type	Description
apiFilename	string	Name of the file where the API file will be stored.
correlationId	string	CorrelationId when logging activities.
options	object	Options associated with the call. Used to pass metrics to rpRetry and apiInfo to access the api file in the api provider.

swagger-helper~rejectRequest(error, context, res, logLevel, parameters) ⇒ void

The error has the following format:

{
   "statusCode": "http code for the response",
   "title": "http title associated with the http code",
   "message": "error.message or `no error message` if the error does not exist",
   "info": "information contained in the error"
}

The swagger options object has the following properties:

{
   "swagger": {
     "method": "method of the request",
     "path": "path of the request",
     "operationId": "operation defined for that route"
   },
   "correlationId": "correlationId included in the header of the request if present otherwise UUID"
}

The parameters object has the following optional properties:

{
   "rfc": "to indicate the error needs to be in rfc format and could be in the error itself, if present the value is 7807",
   "headers": "object with properties that need to be added to the header of the response"
}

If an error of statusCode 500 or above is to be sent, and if logger is enabled but logLevel is not set, an error level log will be generated, otherwise a warning level log will be generated.

Kind: inner method of swagger-helper
Category: sync
Requires: module:@mimik/sumologic-winston-logger

Param	Type	Description
error	object	The error to include in the response.
context	object	Context created by the openAPI middleware.
res	object	The http response object.
logLevel	string | boolean	To indicate if the response will be logged or not (false or undefined or invalid will indicate that the log is done with error level). If set to true, will indicate that no log should be done.
parameters	object	Parameters to add or configure the response.

swagger-helper~convertParams(context, logLevel) ⇒ object

Inspects the supplied swagger params and, if a value exists on the property, adds the property name and value to the options object. swagger and correlationId are reserved and cannot be used in the swagger file. This function will also coerce the parameter to the proper type for the parameters in path, the query and the header. It will also use the default value of the api definition if the property either does not exist or is set to null.

Kind: inner method of swagger-helper
Returns: object - The converted object.
Category: sync
Requires: module:@mimik/request-helper, module:@mimik/sumologic-winston-logger

Param	Type	Description
context	object	The context generated by the middleware.
logLevel	string | boolean	To indicate if the response will be logged or not (false or undefined or invalid will indicate that the log is done with info level). If set to true, will indicate that no log should be done.