# openapi-enforcer

> Library for validating, parsing, and formatting data against open api schemas.

Latest version **1.23.0** (published 2024-03-02) · Apache-2.0 license · 0 weekly downloads

## Install

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

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.23.0 |
| Published | 2024-03-02 |
| First published | 2017-11-15 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 97 |
| Author | James Speirs |
| Maintainers | gi60s |
| Keywords | openapi, swagger, validate, response, build, compose, parse, format, deserialize, serialize, request validation, request parsing, response validation, response serializing, utility, utils, plugable |

## Links

- npm: https://www.npmjs.com/package/openapi-enforcer
- Repository: https://github.com/byu-oit/openapi-enforcer
- Homepage: https://openapi-enforcer.com
- Issues: https://github.com/byu-oit/openapi-enforcer/issues
- npm.io page: https://npm.io/package/openapi-enforcer

## Dependencies (2)

- [js-yaml](https://npm.io/package/js-yaml.md) ^4.1.0
- [randexp](https://npm.io/package/randexp.md) ^0.5.3

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.23.0 (latest) — 2024-03-02
- 0.11.6 (v0-latest) — 2019-04-18
- 1.22.3 — 2023-05-05
- 1.22.2 — 2022-12-06
- 1.22.1 — 2022-11-03
- 1.22.0 — 2022-10-06
- 1.21.1 — 2022-09-22
- 1.21.0 — 2022-05-18
- 1.20.0 — 2022-05-17
- 1.19.0 — 2022-05-01
- 1.18.0 — 2022-03-31
- 1.17.2 — 2022-03-31
- 1.17.1 — 2022-03-30
- 1.17.0 — 2022-02-09
- 1.16.1 — 2021-12-10
- … 116 more at https://npm.io/package/openapi-enforcer/versions

## README

# OpenAPI-Enforcer

Tools for using the Open API Specification (OAS)

**Supports OAS 2.0 (formerly Swagger) and OAS 3.x.x**

## Features

- Create an API.
- Validate your OAS documents.
- Serialize, deserialize, and validate values against OAS schemas.
- Identify the operation associated with a request.
- Parse, deserialize, and validate request parameters.
- Facilitated response building.
- Generate random valid values for a schema.
- Plugin environment for custom document validation and extended functionality including custom data type formats.

## Website - [openapi-enforcer.com](https://openapi-enforcer.com/)

## Installation

```shell
npm install openapi-enforcer
```

## Examples

### Loading and Validating a Document

Use the Enforcer to load and resolve all $ref values and then to validate the complete document.

```js
const Enforcer = require('openapi-enforcer')

async function run () {
  const [openapi, error, warning] = await Enforcer('./path/to/openapi.yml', {
    fullResult: true
  })
  if (error !== undefined) console.error(error)
  if (warning !== undefined) console.warn(warning)
  if (openapi !== undefined) console.log('Document is valid')
}

run.catch(console.error)
```

### Processing an Incoming Request

```js
const Enforcer = require('openapi-enforcer')

async function run () {
  // Because we don't specify `fullResult: true`, any errors will throw an exception and
  // warnings will be logged to the console.
  const openapi = await Enforcer('./path/to/openapi.yml')

  // If the request is valid then the req object will contain the parsed and validated request.
  // If it is invalid then the error will contain details about what was wrong with the
  // request and these details are safe to return to the client that made the request.
  const [ req, error ] = openapi.request({
    method: 'POST',
    path: '/tasks',
    // the body should be parsed by a JSON.parse() prior to passing in (if applicable).
    body: { task: 'Buy Milk', quantity: 2 }
  })

  // You can use the req.operation property to look at the properties from your OpenAPI document.
  // A good use of this is to look at the operationId you defined there to determine which path
  // is being used to handle the request.
  if (req.operaton.operationId === 'my-operation-id') {
    // ... additional request processing
  }
}

run.catch(console.error)
```

### Producing a Valid Result

```js
const Enforcer = require('openapi-enforcer')

async function run () {
  const openapi = await Enforcer('./path/to/openapi.yml')

  const [ req ] = openapi.request({
    method: 'POST',
    path: '/tasks',
    // the body should be parsed by a JSON.parse() prior to passing in (if applicable).
    body: { task: 'Buy Milk', quantity: 2 }
  })

  const body = { id: 1, task: 'Buy Milk', quantity: 2, dateCompleted: null }
  const headers = {}

  // This will validate the response code, body, and headers. It will also correctly serialize
  // the body and headers for sending to the client that made the request. Using this method
  // you'll never send back a response that does not match what your OpenAPI document defines.
  const [ res, error ] = req.response(200, body, headers)
  console.log(res.body, res.headers)
}

run.catch(console.error)
```

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