# express-openapi-json

> Builds an express-compatible router using OpenAPI with request and response validation.

Latest version **3.3.3** (published 2020-08-15) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install express-openapi-json
pnpm add express-openapi-json
yarn add express-openapi-json
bun add express-openapi-json
```

Provides the command `openapi2ts`.

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 3.3.3 |
| Published | 2020-08-15 |
| First published | 2019-06-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 89.6 KB |
| Known vulnerabilities | 0 (+2 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Roel van Uden |
| Maintainers | deathspike |
| Keywords | ajv, express, openapi, router, validator |

## Links

- npm: https://www.npmjs.com/package/express-openapi-json
- Repository: https://github.com/Deathspike/express-openapi-json
- Homepage: https://github.com/Deathspike/express-openapi-json#readme
- Issues: https://github.com/Deathspike/express-openapi-json/issues
- npm.io page: https://npm.io/package/express-openapi-json

## Dependencies (2)

- [ajv](https://npm.io/package/ajv.md) 6.12.3
- [path-to-regexp](https://npm.io/package/path-to-regexp.md) 6.1.0

## Alternatives

- [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads
- [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads
- [@bitkyc08/opencodex](https://npm.io/package/@bitkyc08/opencodex.md) — 4.6K weekly downloads
- [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads
- [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads

## Recent versions

- 3.3.3 (latest) — 2020-08-15
- 3.3.2 — 2020-08-15
- 3.3.1 — 2020-08-15
- 3.3.0 — 2020-08-15
- 3.2.0 — 2020-08-11
- 3.1.0 — 2020-08-08
- 3.0.0 — 2020-08-07
- 2.0.0 — 2020-02-14
- 1.3.0 — 2020-02-14
- 1.2.0 — 2019-10-18
- 1.1.6 — 2019-06-26
- 1.1.5 — 2019-06-24
- 1.1.4 — 2019-06-22
- 1.1.3 — 2019-06-22
- 1.1.2 — 2019-06-22
- … 4 more at https://npm.io/package/express-openapi-json/versions

## README

# ExpressJS + OpenAPI + JSON = <3

Builds an express-compatible router using `OpenAPI` with request and response validation.

## Assumptions

* Your `ExpressJS` server includes `body-parser` and `cookie-parser` when applicable.
* Your `OpenAPI` document is version `3.0` and valid (See https://editor.swagger.io/).
* Your `OpenAPI` document consumes `application/json` and produces `application/json`.
* Your `OpenAPI` document operations declare an  `operationId`.

## Installation

Install `express-openapi-json`:

```
npm install express-openapi-json
```

## Quick Start

Create a router with one operation for the specified `operationId`:

```js
const router = api.createCore(require('./openapi.json'))
  .operation('getUserById', ctx => api.json({id: ctx.query.id})))
  .router();
```

Create a router with one controller (using `decorators`):

```js
class PersonController {
  @api.createOperation('getUser')
  get(context) {
    return api.json({id: context.query.id});
  }
}

const router = api.createCore(require('./openapi.json'))
  .controller(new PersonController())
  .router();
```

Using the router in `express`:

```js
app.use(router.express());
```

Using the router in `express` mounted under `/api`:

```js
app.use('/api', router.express());
```

## Full Example

```js
import api from 'express-openapi-json';
import bodyParser from 'body-parser';
import cookieParser from 'cookie-parser';
import express from 'express';

class UserController {
  @api.createOperation('getUser')
  get(context) {
    return api.json({id: context.query.id});
  }

  @api.createOperation('postUser')
  post(context) {
    return api.status(200);
  }
}

const router = api.createCore(require('./openapi.json'))
  .controller(new UserController())
  .router();

const server = express();
server.use(bodyParser.json());
server.use(cookieParser());
server.use(router.express());
server.listen(3000);
```

# Scripts

Certain scripts are made available after package installation.

## openapi2ts

Converts an `openapi` document to `TypeScript` definitions. Limitations:

* Your `OpenAPI` document must be stored as `json`.

Installation:

    npm install json-schema-to-typescript --save-dev

Usage:

    openapi2js your_openapi.json > your_typescript.ts

# OpenAPI

This section describes the supported features and limitations.

## Paths

    {
      paths: {
        [Path]: {
          [method]: Operation = {
            parameters?: Parameter[],
            requestBody?: RequestBody
            responses: {
              [responseKey]: Response
            }
          }
        }
      }
    }

### Path

Supported.

### Parameter (Operation)

Supported with validation (including `required`). Limitations:

* Parameter **MUST** have a `schema` or `$ref`. See [Schema](#Schema).
* Parameter **MUST** have a `schema.type` that is a primitive:
  * `boolean` (`/^(1|0|true|false|yes|no)$/i`)
  * `integer` (`/^[0-9]+$/`)
  * `number` (`/^[0-9]+(\.[0-9]+)?$/`)
  * `string`

### RequestBody (Operation)

Supported with validation. Limitations:

* Content **MUST** have a `contentType` = `application/json`.
* Content **MUST** have a `schema` for `application/json`. See [Schema](#Schema).

### Response (Operation)

Supported. See [Components](#Components).

## Components

    {
      components: {
        responses?: {
          [responseName]: Response = {
            headers?: Headers
            content?: Content
          }
        }
        schemas?: {
          [schemaName]: Schema
        }
      }
    }

### Headers (Response)

Unsupported.

### Content (Response)

Supported with validation. Limitations:

* Content **SHOULD** have a `contentType` = `application/json`.
* Content **MUST** have a `schema` for `application/json`. See [Schema](#Schema).

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