# openapi-refinements

> Refine OpenAPI schemas to valid sub-OpenAPI scheams.

Latest version **0.3.18** (published 2020-05-24) · MIT license · 0 weekly downloads

## Install

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

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.18 |
| Published | 2020-05-24 |
| First published | 2019-09-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 201.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | meeshkan |

## Links

- npm: https://www.npmjs.com/package/openapi-refinements
- Repository: https://github.com/unmock/unmock-js
- Issues: https://github.com/unmock/unmock-js/issues
- npm.io page: https://npm.io/package/openapi-refinements

## Dependencies (1)

- [@meeshkanml/jsonschema](https://npm.io/package/@meeshkanml/jsonschema.md) ^0.0.1

## Recent versions

- 0.3.18 (latest) — 2020-05-24
- 0.3.17 — 2020-04-16
- 0.3.12 — 2020-01-10
- 0.3.11 — 2019-12-19
- 0.3.10 — 2019-11-07
- 0.3.9 — 2019-10-17
- 0.3.8 — 2019-10-02
- 0.3.7 — 2019-09-26
- 0.3.6 — 2019-09-26
- 0.3.5 — 2019-09-25
- 0.3.4 — 2019-09-22
- 0.3.3 — 2019-09-20
- 0.3.2 — 2019-09-18
- 0.3.1 — 2019-09-18
- 0.3.0 — 2019-09-17
- … 19 more at https://npm.io/package/openapi-refinements/versions

## README

# openapi-refinements

Refine OpenAPI schemas to valid sub-OpenAPI scheams.

## Example of a refinement

Imagine that you had the following bit of JSON schema.

```yaml
type: string
enum: [foo, bar, baz]
```

A valid refinement would be the following.

```yaml
type: string
enum: [foo, baz]
```

In general a refinement is any Schema that produces a subset of the behavior of another Schema.  In this case, because we are dealing with OpenAPI, an API behaving according to the refined OpenAPI schema will only produce outcomes that would have been possible with the original OpenAPI schema, but not vice-versa.

## API

### `includeCodes` and `removeCodes`

```ts
includeCodes(
  info: [string | RegExp, Meth] | string | RegExp,
  r: (keyof Responses)[]
) => (o: OpenAPIObject): OpenAPIObject
```

Produce an OpenAPI schema to OpenAPI schema mapping that includes codes in `r` (ie 200, 404, default) for a path (`string` or `RegExp`) and possibly an operation (`Meth`).

To produce an OpenAPI schema to OpenAPI schema mapping that only includes the default response for every possible path, use the following.

```ts
const mapping = includeCodes(new RegExp("[a-zA-Z0-9/{}]*"), ["default"]);
```

To produice an OpenAPI schema to OpenAPI schema mapping that removes `"200"` and `"default"` from the `get` method of the path `/foo`, use the following.

```ts
const mapping = removeCodes(["/foo", "get"], ["200", "default"]);
```

## Changing paramaters, request bodies and response bodies

All changes to parameters, request bodies and response bodies represent first the change in a schema (here, "schema" means the `Schema` object in an OpenAPI Schema, which is effectively JSON schema) followed by instructions on how to reach the Schema.

For example, the signature for `changeMaxItems` is the following.

```ts
const changeMaxItems = (i: number) =>
  (
    traversal: (o: OpenAPIObject) => Traversal<OpenAPIObject, Schema | Reference>,
    path: (string | typeof Arr)[]
  ) => (o: OpenAPIObject) => OpenAPIObject
```

`i` represents the change to `maxNumbers`. `traversal` represents the path we take to get the the `Schema` we want to change, and `path` represents the path we take once we are in the `Schema`. Then, like `includeCodes` above, an OpenAPI Schema to OpenAPI Schema mapping is returned.

Another example is `changeToConst`.

```ts
const changeToConst = (val: JSONValue) =>
  (
    traversal: (o: OpenAPIObject) => Traversal<OpenAPIObject, Schema | Reference>,
    path: (string | typeof Arr)[]
  ) => (o: OpenAPIObject) => OpenAPIObject
```

The signature is almost exactly the same as above save the first element `val`, which is the constant value we are changing. For all of the following functions, the first part of the signature will be different whereas the last three parts will be the same. As a result, this section will be broken into two parts. First, we will explain the `traversal` and `path`, and then, we will explain the various actions like `changeMinItems` or `changeEnum`.

### `traversal` and `path`

`traversal` represents a `monocle-ts` traversal down to an object in an OpenAPI structure. You do not have to define your own traversals - rather, there are pre-defined traversal creators that will do this for you.

- `pathParameter` is a traversal to a parameter in a path
- `methodParameter` is a traversal to a parameter in a method
- `requestBody` is a traversal to a parameter in a request body
- `responseBody` is a traversal to a parameter in a response body

The tests show various examples of all of these traversals.

`path` represents a path *within* the object. For example, if the object is:

```yaml
type: object
properties:
  foo:
    type: object
    additionalProperties:
        type: array
        items:
        type: array
            items: [{type: string}, {type: integer}]
```

Then the path to access the second element of all the arrays of any additional property of `foo` would be `["foo", Addl, Arr, 1]`, where `Arr` is a special symbol meaning all elements in an array and `Addl` is a special symbol meaning any additional property.

### Methods

The following methods are defined for schema changes.

- `changeMinItem`
- `changeMaxItem`
- `changeToConst`
- `changeEnum`
- `changeListToTuple`
- `anyOfKeep`
- `anyOfReject`
- `oneOfKeep`
- `oneOfReject`

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