npm package: @mimik/swagger-helper
Description: Swagger helper for mimik microservices
Author: mimik technology inc
Latest version: 5.0.5

<a name="module_swagger-helper"></a>

## swagger-helper
**Example**  
```js
import swaggerHelper from '@mimik/swagger-helper';
```
**Example**  
```js
import { TOKEN_PARAMS, getAPIFile, rejectRequest, convertParams } from '@mimik/swagger-helper';
```

* [swagger-helper](#module_swagger-helper)
    * _async_
        * [~getAPIFile(apiFilename, correlationId, options)](#module_swagger-helper..getAPIFile) ⇒ <code>Promise.&lt;object&gt;</code>
    * _sync_
        * [~rejectRequest(error, context, res, logLevel, parameters)](#module_swagger-helper..rejectRequest) ⇒ <code>void</code>
        * [~convertParams(context, logLevel)](#module_swagger-helper..convertParams) ⇒ <code>object</code>

<a name="module_swagger-helper..getAPIFile"></a>

### swagger-helper~getAPIFile(apiFilename, correlationId, options) ⇒ <code>Promise.&lt;object&gt;</code>
Gets the API file from bitbucket or swaggerhub and stores it in the given PATH location.

**Kind**: inner method of [<code>swagger-helper</code>](#module_swagger-helper)  
**Returns**: <code>Promise.&lt;object&gt;</code> - The API file itself.  
**Category**: async  
**Throws**:

- <code>Error</code> 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.

`apiInfo` options has the following format:
``` javascript
{
   "provider": "provider of the api file, can be `swaggerhub` or `bitbucket`",
   "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**: <code>module:@mimik/request-retry</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:fs</code>, <code>module:js-yaml</code>, <code>module:path</code>  

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

<a name="module_swagger-helper..rejectRequest"></a>

### swagger-helper~rejectRequest(error, context, res, logLevel, parameters) ⇒ <code>void</code>
The error has the following format:
``` javascript
{
   "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:
``` javascript
{
   "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:
``` javascript
{
   "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 above 500 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 [<code>swagger-helper</code>](#module_swagger-helper)  
**Category**: sync  
**Requires**: <code>module:@mimik/sumologic-winston-logger</code>  

| Param | Type | Description |
| --- | --- | --- |
| error | <code>object</code> | The error to include in the response. |
| context | <code>object</code> | Context created by the openAPI middleware. |
| res | <code>object</code> | The http response object. |
| logLevel | <code>string</code> \| <code>boolean</code> | 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 | <code>object</code> | Parameters to add or configure the response |

<a name="module_swagger-helper..convertParams"></a>

### swagger-helper~convertParams(context, logLevel) ⇒ <code>object</code>
Inspect 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 [<code>swagger-helper</code>](#module_swagger-helper)  
**Returns**: <code>object</code> - The converted object.  
**Category**: sync  
**Requires**: <code>module:@mimik/request-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>  

| Param | Type | Description |
| --- | --- | --- |
| context | <code>object</code> | The context generated by the middleware. |
| logLevel | <code>string</code> \| <code>boolean</code> | 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. |