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:

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

Create a router with one controller (using decorators):

1class PersonController {
2  @api.createOperation('getUser')
3  get(context) {
4    return api.json({id: context.query.id});
5  }
6}
7
8const router = api.createCore(require('./openapi.json'))
9  .controller(new PersonController())
10  .router();

Using the router in express:

1app.use(router.express());

Using the router in express mounted under /api:

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

Full Example

1import api from 'express-openapi-json';
2import bodyParser from 'body-parser';
3import cookieParser from 'cookie-parser';
4import express from 'express';
5
6class UserController {
7  @api.createOperation('getUser')
8  get(context) {
9    return api.json({id: context.query.id});
10  }
11
12  @api.createOperation('postUser')
13  post(context) {
14    return api.status(200);
15  }
16}
17
18const router = api.createCore(require('./openapi.json'))
19  .controller(new UserController())
20  .router();
21
22const server = express();
23server.use(bodyParser.json());
24server.use(cookieParser());
25server.use(router.express());
26server.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
    }
  }
}

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.