Express-openapi-json NPM

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:

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):

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:

app.use(router.express());

Using the router in express mounted under /api:

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

Full Example

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

Response (Operation)

Supported. See Components.

Components

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