# ut-openapi

> Open api utilities

Latest version **1.3.5** (published 2023-09-29) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install ut-openapi
pnpm add ut-openapi
yarn add ut-openapi
bun add ut-openapi
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.5 |
| Published | 2023-09-29 |
| First published | 2019-12-11 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 82.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Software Group |
| Maintainers | kalin.krustev |
| Keywords | openapi, openapi utilities, swagger, swagger utilities |

## Links

- npm: https://www.npmjs.com/package/ut-openapi
- Repository: https://github.com/softwaregroup-bg/ut-openapi
- Homepage: https://github.com/softwaregroup-bg/ut-openapi#readme
- Issues: https://github.com/softwaregroup-bg/ut-openapi/issues
- npm.io page: https://npm.io/package/ut-openapi

## Dependencies (3)

- [ut-function.merge](https://npm.io/package/ut-function.merge.md) ^1.5.5
- [ut-function.interpolate](https://npm.io/package/ut-function.interpolate.md) ^1.1.3
- [@apidevtools/swagger-parser](https://npm.io/package/@apidevtools/swagger-parser.md) 10.0.3

## Recent versions

- 1.3.5 (latest) — 2023-09-29
- 1.2.2-dfa.0 (dfa) — 2020-07-31
- 1.3.4 — 2022-04-20
- 1.3.3 — 2021-10-21
- 1.3.2 — 2020-11-15
- 1.3.1 — 2020-10-19
- 1.3.0 — 2020-07-31
- 1.2.1 — 2020-07-13
- 1.2.0 — 2020-06-02
- 1.1.0 — 2020-02-24
- 1.0.3 — 2020-02-17
- 1.0.2 — 2019-12-23
- 1.0.1 — 2019-12-11
- 0.1.1 — 2019-12-11

## README

# UT OpenAPI

This module provides automatic message formatting
for http clients consuming swagger-enabled APIs.
Currently only [request](https://www.npmjs.com/package/request)
[format](./format/request.js) is supported.

## Usage

ut-openapi exports a factory function which
returns an object with the following methods:

* `async load (documents)` - loads a set
of documents and binds message formatters in
the local cache. Example:

  ```js
    const utOpenApi = require('ut-openapi')();
    utOpenApi.load({ // documents
        'providerX.segmentX': require.resolve('./providerX/segmentX-swagger.json'),
        'providerX.segmentY': require.resolve('./providerX/segmentY-swagger.json'),
        'providerY': require('./providerY-swagger.json'),
        'providerZ': 'http://www.providerZ.com/swagger.json'
    });

    /*
        there is a short syntax
        if just one document must be loaded.
        Instead of a map, just pass the namespace
        and the document as separate arguments:
    */
   utOpenApi.load('someProvider', require('./someProviderSwagger.json'));
  ```

  The `documents` argument represents a map where:

  * the keys determine how the operation IDs of the
  document will be prefixed. For example if the
  document is prefixed with key `providerX.segmentY`
  and contains a route with operationId `operationZ`,
  then it will be accessible via the method
  `providerX.segmentY.operationZ`. Example:

  ```js
    const utOpenApi = require('ut-openapi')();
    utOpenApi.load({ // documents
        'providerX.segmentY': {
            "swagger": "2.0",
            // ...
            "paths": {
                "/path": {
                    "post": {
                        "operationId": "operationZ"
                    }
                }
            }
        }
    });
  ```

  * the values are the documents themselves.
  All three approaches are acceptable as a value:

    * path to a local swagger document
    * the content of the swagger document
    * url for obtaining the document with http `GET` request

* `format (msg, method, format)`
  * `msg` (object) - the message to be sent
  * `method` (string) - the bound formatter function
  * `format` (string) - the format. Only `request` is
    currently supported.

  The message format for calling these auto-generated
  swagger methods has the following specifics:

  * can have a `body` property which will be used
  as a payload
  * can have a `params` property which ill be used
  for extracting `path`, `query` and `header` parameters.

  ```js
    const utOpenApi = require('ut-openapi')();
    utOpenApi.load({ // documents
        'providerX.segmentY': {
            "swagger": "2.0",
            "host": "127.0.0.1:8080",
            "schemes": ["http"],
            "basePath": "/test",
            // ...
            "paths": {
                "/path/{pathParam}": {
                    "post": {
                        "operationId": "operationZ",
                        "parameters": [
                            {
                                "in": "path",
                                "name": "pathParam",
                                "type": "string"
                            },
                            {
                                "in": "body",
                                "name": "body",
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "y": {
                                            "type": "boolean"
                                        }
                                    }
                                }
                            }
                        ]
                    }
                }
            }
        }
    });
    const requestMessage = utOpenApi.format({
        params: {
            pathParam: 'x'
        },
        body: {
            y: true
        }
    }, 'providerX.segmentY.operationZ', 'request');
    /* requestMessage will result in a format suitable
    for usage with the node.js 'request' module:
        {
            url: 'http://127.0.0.1:8080/test/path/x',
            method: 'get',
            body: {
                y: true
            },
            headers: {},
            qs: {}
        }
    */
  ```

* `formatRequest (msg, method)`
Shorthand for `format` function. E.e.
`formatRequest({/*...*/}, 'providerX.segmentY.operationZ')`
equals `format({/*...*/}, 'providerX.segmentY.operationZ', 'request')`
* `export (format, pattern)`
This is a convenient wrapper for obtaining
multiple formatters simultaneously based on a pattern.

E.g.

```js
    const utOpenApi = require('ut-openapi')();
    utOpenApi.load({ // documents
        'providerX.segmentX': {
            "swagger": "2.0",
            // ...
            "paths": {
                "/path1": {
                    "post": {
                        "operationId": "a.operation"
                    }
                },
                 "/path1": {
                    "post": {
                        "operationId": "b.operation"
                    }
                }
            }
        },
        'providerX.segmentY': {
            "swagger": "2.0",
            // ...
            "paths": {
                "/path1": {
                    "post": {
                        "operationId": "a.operation"
                    }
                },
                 "/path1": {
                    "post": {
                        "operationId": "b.operation"
                    }
                }
            }
        }
    });

    const formatters1 = utOpenApi.export();
    /*
        {
            'providerX.segmentX.a.operation': params => {},
            'providerX.segmentX.b.operation': params => {},
            'providerX.segmentY.a.operation': params => {},
            'providerX.segmentY.b.operation': params => {}
        }
    */

   const formatters2 = utOpenApi.export('request', 'providerX.segmentX');
    /*
        {
            'providerX.segmentX.a.operation': params => {},
            'providerX.segmentX.b.operation': params => {}
        }
    */

   const formatters3 = utOpenApi.export('request', 'a.operation');
    /*
        {
            'providerX.segmentX.a.operation': params => {},
            'providerX.segmentY.a.operation': params => {}
        }
    */

   // also regular expressions are supported
   const formatters4 = utOpenApi.export('request', /\.a\./);
    /*
        {
            'providerX.segmentX.a.operation': params => {},
            'providerX.segmentY.a.operation': params => {}
        }
    */
```

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