# @mimik/swagger-helper

> Swagger helper for mimik microservices

Latest version **5.1.1** (published 2026-07-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install @mimik/swagger-helper
pnpm add @mimik/swagger-helper
yarn add @mimik/swagger-helper
bun add @mimik/swagger-helper
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 5.1.1 |
| Published | 2026-07-08 |
| First published | 2018-06-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=24.0.0 |
| Dependencies | 7 |
| Unpacked size | 25.6 KB |
| Known vulnerabilities | 0 (+3 in 1 direct dependencies) |
| Install scripts | no |
| Author | mimik technology inc |
| Maintainers | mimik-npm-editor, hofachiang, miburger, mimikopensource, sasan.raisdana |
| Keywords | mimik, microservice |

## Links

- npm: https://www.npmjs.com/package/@mimik/swagger-helper
- Repository: https://bitbucket.org/mimiktech/swagger-helper
- Homepage: https://bitbucket.org/mimiktech/swagger-helper#readme
- Issues: https://bitbucket.org/mimiktech/swagger-helper/issues
- npm.io page: https://npm.io/package/@mimik/swagger-helper

## Dependencies (7)

- [js-yaml](https://npm.io/package/js-yaml.md) 4.2.0
- [js-base64](https://npm.io/package/js-base64.md) 3.7.8
- [swagger-client](https://npm.io/package/swagger-client.md) 3.37.5
- [@mimik/request-retry](https://npm.io/package/@mimik/request-retry.md) ^4.0.10
- [@mimik/address-helper](https://npm.io/package/@mimik/address-helper.md) ^2.0.8
- [@mimik/request-helper](https://npm.io/package/@mimik/request-helper.md) ^2.0.6
- [@mimik/sumologic-winston-logger](https://npm.io/package/@mimik/sumologic-winston-logger.md) ^2.2.2

## Recent versions

- 5.1.1 (latest) — 2026-07-08
- 5.0.5 — 2026-03-22
- 5.0.4 — 2026-03-13
- 5.0.3 — 2026-02-23
- 5.0.2 — 2025-07-19
- 5.0.1 — 2025-04-16
- 5.0.0 — 2025-04-16
- 4.0.10 — 2024-10-04
- 4.0.9 — 2023-12-05
- 4.0.8 — 2023-05-03
- 4.0.7 — 2023-05-03
- 4.0.6 — 2023-04-27
- 4.0.5 — 2023-04-27
- 4.0.4 — 2023-04-27
- 4.0.3 — 2023-04-25
- … 33 more at https://npm.io/package/@mimik/swagger-helper/versions

## README

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

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:
``` javascript
{
   "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**: <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. Used 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 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 [<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>
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 [<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 `info` level). If set to `true`, will indicate that no log should be done. |

---
_Source: https://npm.io/package/@mimik/swagger-helper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._