Express-typescript-decorators NPM

Express TypeScript Decorators

Create Express APIs using TypeScript decorators that naturally generate OpenAPI documentation to describe your API.

Working Example

See a working example of express-typescript-decorators User Management

Overview

Create classes whose methods represent Express routes
Decorate your class to add additional Express functionality i.e. @Controller(), @HttpGet, @Middleware etc.
Further Describe your API with a title and description in OpenAPI.json
Automatically generate OpenAPI JSON documentation
Link your API documentation to Swagger for rich API documentation tools

Typedoc Documentation

Example Application

Consider the following three examples to see how any Express application can become a fully documented API.

Example Express Application before using Express TypeScript Decorators

Here is an example of an Express Application without TypeScript.

controllers/user.js

const express = require('express');
const UserService = require('../services/user');

const router = express.Router();

router.post('/user', async (req, res) => {
    const username = req.body.username;
    const password = req.body.password;

    try {
        const user = await UserService.create(username, password);
        res.status(201).send(user);
    } catch(e) {
        res.send(400);
    }
});

router.get('/user', async (req, res) => {
    const users = await UserService.list();
    res.send(users);
});

module.exports = router;

index.js

const express = require('express');
const bodyParser = require('body-parser');
const UserController = require('./src/controllers/user');
const app = express();

app.use(bodyParser.json());

app.use('/api', UserController);
app.listen(3000, () => console.log('Express Application Started!'));

Converting to TypeScript and Decorators

Here's how this same Express Application would be implemented using Decorators and TypeScript

controllers/user.ts

import UserService from '../services/user';
import {
    Controller,
    HttpPost,
    HttpGet,
    Response,
    ExpressResponse
} from 'express-typescript-decorators';

@Controller()
class UserController {

    @HttpPost('/user')
    async createUser(
        @RequestParam('username') username: string,
        @RequestParam('password') password: string,
        @Response() res: ExpressResponse
    ): Promise<void> {
        try {
            const user = await UserService.create(username, password);
            res.status(201).send(user);
        } catch(e) {
            res.send(400);
        }
    }

    @HttpGet('/user')
    async listUsers(
        @Response() res: ExpressResponse
    ): Promise<void> {
        const users = await UserService.list();
        res.send(users);
    }
}

export default router;

index.ts

import express from 'express';
import bodyParser from 'body-parser';
import {useController} from 'express-typescript-decorators';
import UserController from './src/controllers/user';

const app = express();

app.use(bodyParser.json());
app.use('/api', useController(UserController));
app.listen(3000, () => console.log('Express Application Started!'));

Full Swagger API Documentation Example

Taking this example Express Application a step further, we can produce more comprehensive API documentation in our code with the addition of @HttpReponse, @RequestBody and providing descriptions in calls to @RequestParam. This content naturally flows into Swagger UI.

controllers/user.ts

import UserService from '../services/user';
import {
    Controller,
    HttpPost,
    HttpGet,
    HttpResponse,
    RequestBody,
    Response,
    ExpressResponse
} from 'express-typescript-decorators';

@Controller()
class UserController {

    @RequestBody('application/json', 'POST Body that contains all information required to create a user', true)
    @HttpResponse(201, 'User Created Successfully', 'application/json', {
      id: 123,
      firstName: "Paul",
      lastName: "Forbes",
      email: "paulforbes42@gmail.com"
    })
    @HttpResponse(400, 'Failed to create user')
    @HttpPost('/user', 'Create a new user for the system')
    async createUser(
        @RequestParam('username', 'Username for the new user record', 'exampleUsername') username: string,
        @RequestParam('password', 'Password for the new user record', 'Pa33w0rd') password: string,
        @Response() res: ExpressResponse
    ): Promise<void> {
        try {
            const user = await UserService.create(username, password);
            res.status(201).send(user);
        } catch(e) {
            res.send(400);
        }
    }

    @HttpGet('/user', 'Generate a list of users in the system')
    async listUsers(
        @Response() res: ExpressResponse
    ): Promise<void> {
        const users = await UserService.list();
        res.send(users);
    }
}

export default router;

index.ts

import express from 'express';
import bodyParser from 'body-parser';
import {
    getOpenAPIJson,
    setOpenAPIInfo,
    useController,
} from 'express-typescript-decorators';
import UserController from './src/controllers/user';

const app = express();

setOpenAPIInfo({
    title: "Example User API",
    summary: "A sample Express Application to create and list users",
    description: "This sample Express Application demonstrates usage of decorators to create Express Routers called 'controllers' from Classes.  Methods of the class can represent the routes of the Express Application when correctly decorated.  Optionally, OpenAPI documentation can be generated to describe the API.",
    contact: {
        name: "Paul Forbes",
        email: "paulforbes42@gmail.com"
    },
    license: {
        name: "Apache 2.0",
        identifier: 'Apache-2.0',
        url: "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    version: "0.0.1"
});

app.use(bodyParser.json());
app.use('/api', useController(UserController));
app.use('/api-docs', getOpenApiJson());
app.listen(3000, () => console.log('Express Application Started!'));

Navigating to http://localhost:3000/api-docs will provide a JSON representation of the OpenAPI documentation you've created directly from the code for your API.

TypeScript configuration tsconfig.json

The following configurations will need to be enabled in tsconfig.json for your project order for the decorators to appropriately capture metadata from you controllers and routes.

tsconfig.json

{
    "compilerOptions": {
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true
    }
}

Decorators and Utility Methods

The ulitmate goal of this package is to allow a clean and consistent interface to provide rich OpenAPI documentation around your API while, alternatively, supporting a simple approach to define class based Express routers in TypeScript. Observe the following Decorators and utility methods at your disposal. The more optional information you provide about each route, the more content which will be available in your OpenAPI JSON file which can be consumed by Swagger UI for an always up-to-date API documentation site.

Decorators

Controller

▸ @Controller<T>(path?, tag?, description?)

Class decorator used for classes that represent a grouping of Express routes

Example

@Controller('/api', 'User', 'User Management Routes')
class User {
 ...
}

Parameters

Name	Type	Description
`path?`	`string`	URL path to prefix all Express routes within the class
`tag?`	`string`	OpenAPI grouping for all Express routes within the class
`description?`	`string`	OpenAPI description that will be associated with the tag for this class

HttpDelete

▸ @HttpDelete<T>(path, description?)

Method decorator that indicates the method should be accessible through an HTTP Delete operation

Example

@Controller('/api', 'User', 'User Management Routes')
class User {

 @HttpDelete('/user', 'Mark a user as deleted')
 async deleteUser(
   @RequestParam('userId') userId: number, 
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

Parameters

Name	Type	Description
`path`	`string`	URL which this method should be access through as a HTTP Delete operation
`description?`	`string`	Description of this route to be included in the OpenAPI documentation

HttpGet

▸ @HttpGet<T>(path, description?)

Method decorator that indicates the method should be accessible through an HTTP Get operation

Example

@Controller('/api', 'User', 'User Management Routes')
class User {

 @HttpGet('/user', 'List users in the system')
 async listUsers(
   @Query('search') search: string,
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

Parameters

Name	Type	Description
`path`	`string`	URL which this method should be access through as a HTTP Get operation
`description?`	`string`	Description of this route to be included in the OpenAPI documentation

HttpPost

▸ @HttpPost<T>(path, description?)

Method decorator that indicates the method should be accessible through an HTTP Post operation

Example

@Controller('/api', 'User', 'User Management Routes')
class User {

 @HttpPost('/user', 'Create a new user')
 async createUser(
   @RequestParam('username') username: string,
   @RequestParam('password') password: string,
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

Parameters

Name	Type	Description
`path`	`string`	URL which this method should be access through as a HTTP Post operation
`description?`	`string`	Description of this route to be included in the OpenAPI documentation

HttpPut

▸ @HttpPut<T>(path, description?)

Method decorator that indicates the method should be accessible through an HTTP Put operation

Example

@Controller('/api', 'User', 'User Management Routes')
class User {

 @HttpPut('/user/:userId', 'Update an existing user')
 async createUser(
   @UrlParam('userId') userId: number,
   @RequestParam('password') password: string,
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

Parameters

Name	Type	Description
`path`	`string`	URL which this method should be access through as a HTTP Put operation
`description?`	`string`	Description of this route to be included in the OpenAPI documentation

HttpResponse

▸ @HttpResponse<T>(statusCode, description)

Method decorator which describes an HTTP status code that can be returned by this Express route. This decorator can be applied multiple times to a single Express route to describe all status codes produced by this route.

Example

@Controller('/api', 'User', 'User Management Routes')
class User {
 @HttpResponse(201, 'New user record created', 'application/json', {
   id: 123,
   firstName: "Paul",
   lastName: "Forbes",
   email: "paulforbes42@gmail.com"
 })
 @HttpResponse(400, 'Missing required data')
 @HttpPost('/user', 'Create a new user')
 async createUser(
   @RequestParam('username') username: string,
   @RequestParam('password') password: string,
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

Parameters

Name	Type	Description
`statusCode`	`number`	HTTP status code
`description`	`string`	Description of the scenario in which this HTTP status code will be produced

Middleware

▸ @Middleware<T>(middleware, security?)

Method decorator which accepts an array of Express middleware callback functions to run prior to the Express route being executed

Example

@Controller('/api', 'User', 'User Management Routes')
class User {

 @Middleware([verifyAuthenticated, checkAdminPermissions], [{"bearerAuth":[]}])
 @HttpPost('/user', 'Create a new user')
 async createUser(
   @RequestParam('username') username: string,
   @RequestParam('password') password: string,
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

Parameters

Name	Type	Description
`middleware`	MiddlewareFunction[]	Array of Express middleware callback functions
`security?`	OpenAPISecurityRequirement[]	Array of security requirement objects. Must match one item in the `securitySchemes` in `OpenAPI.json`

Query

▸ @Query<T>(key, summary?, exampleValue?, required?, deprecated?)

Parameter decorator which defines a query string parameter to be provided to the Express route

Example

@Controller('/api', 'User', 'User Management Routes')
class User {

 @HttpGet('/user', 'List users in the system')
 async listUsers(
   @Query('search', 'Search string to lookup users by first or last name', 'Paul', false, false) search: string,
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

Parameters

Name	Type	Description
`key`	`string`	name of parameter in the query string
`summary?`	`string`	description of the parameter for OpenAPI documentation
`exampleValue?`	`string` \| `number` \| `boolean`	example of expected data
`required?`	`boolean`	indicate if this parameter is required
`deprecated?`	`boolean`	indicate if this parameter is deprecated

Request

▸ @Request<T>()

Parameter decorator which injects the Express Request object into the decorated Express route

Example

@Controller('/api', 'User', 'User Management Routes')
class User {

 @HttpGet('/user', 'List users in the system')
 async listUsers(
   @Query('search') search: string,
   @Request() req: ExpressRequest,
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

Parameters

Name	Type
`target`	`T`
`propertyKey`	`string`
`parameterIndex`	`number`

RequestBody

▸ @RequestBody<T>(contentType, description?, required?)

Method decorator to describe the expected request payload

Example

 * @Controller('/api', 'User', 'User Management Routes')
class User {

 @RequestBody('application/json', 'User information for new user record', true) 
 @HttpPost('/user', 'Create a new user')
 async createUser(
   @RequestParam('username') username: string,
   @RequestParam('password') password: string,
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

Parameters

Name	Type	Description
`contentType`	`string`	content type of payload i.e. "application/json"
`description?`	`string`	description of the payload for OpenAPI documentation
`required?`	`boolean`	indicate if the payload is required

RequestParam

▸ @RequestParam<T>(key, summary?, exampleValue?, required?)

Parameter decorator which defines a request body parameter to be provided to the Express route

Example

@Controller('/api', 'User', 'User Management Routes')
class User {

 @HttpPut('/user/:userId', 'Update an existing user')
 async createUser(
   @UrlParam('userId') userId: number,
   @RequestParam('password') password: string,
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

Parameters

Name	Type	Description
`key`	`string`	name of parameter in request body
`summary?`	`string`	description of the parameter for OpenAPI documentation
`exampleValue?`	`string` \| `number` \| `boolean`	example of expected data
`required?`	`boolean`	indicate if this parameter is required

Response

▸ @Response<T>()

Parameter decorator which injects the Express Response object into the decorated route

Example

@Controller('/api', 'User', 'User Management Routes')
class User {

 @HttpGet('/user', 'List users in the system')
 async listUsers(
   @Query('search') search: string,
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

UrlParam

▸ @UrlParam<T>(key, summary?, exampleValue?)

Parameter decorator which defines a url parameter to be provided to the Express route

Example

@Controller('/api', 'User', 'User Management Routes')
class User {

 @HttpPut('/user/:userId', 'Update an existing user')
 async createUser(
   @UrlParam('userId') userId: number,
   @RequestParam('password') password: string,
   @Response() res: ExpressResponse
 ): Promise<void> { 
   ... 
 }
}

Parameters

Name	Type	Description
`key`	`string`	name of parameter in request body
`summary?`	`string`	description of the parameter for OpenAPI documentation
`exampleValue?`	`string` \| `number` \| `boolean`	example of expected data

Functions

getOpenAPIJson

▸ getOpenAPIJson(): (req: Request, res: Response) => void

Return an Express route which will render the OpenAPI documentation for the API in JSON format.

Example

app.use('/api-docs', getOpenAPIJson());

Returns

fn

Get API method

▸ (req, res): void

Parameters

Name	Type
`req`	`Request`
`res`	`Response`

Returns

void

setOpenAPIInfo

▸ setOpenAPIInfo(info): void

Parameters

Name	Type
`info`	`OpenAPIInfo`

Returns

void

setOpenAPIJsonPath

▸ setOpenAPIJsonPath(path): void

Parameters

Name	Type
`path`	`string`

Returns

void

useController

▸ useController(controller): Router

Utility Method to map a controller class be used by Express

Example

app.use('/', useController(UserController));

Parameters

Name	Type	Description
`controller`	`any`	Controller class

Returns

Router

Express Router object with associated routes

OpenAPI.json

You can further expand your OpenAPI documentation with a static file that includes most fields in the OpenAPI Object (see below). By default the system will look for <rootdir>/OpenAPI.json. This path can be overwritten to a custom location with setOpenAPIJsonPath(path: string). When this file is detected, calls to setOpenAPIInfo() and setOpenAPITags() will be ignored.

OpenAPI Object Reference

http://spec.openapis.org/oas/v3.1.0

export type OpenAPI = {
    openapi: string
    info: OpenAPIInfo
    jsonSchemaDialect?: string
    servers?: OpenAPIServers[]
    paths?: OpenAPIPath
    webhooks?: {
        [key: string]: OpenAPIPathItem | OpenAPIReference
    }
    components?: OpenAPIComponents
    security?: OpenAPISecurityRequirement
    externalDocs?: OpenAPIExternalDocumentation
    tags?: OpenAPITag[]
};

OpenAPI.json example

./OpenAPI.json

{
    "info": {
        "title": "Example Decorator API",
        "summary": "A sample Express Application which demostrates the decorator usage",
        "description": "This sample Express Application demonstrates usage of decorators to create Express Routers called 'controllers' from Classes.  Methods of the class can represent the routes of the Express Application when correctly decorated.  Optionally, OpenAPI documentation can be generated to describe the API.",
        "contact": {
            "name": "Paul Forbes",
            "email": "paulforbes42@gmail.com"
        },
        "license": {
            "name": "Apache 2.0",
            "identifier": "Apache-2.0",
            "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
        },
        "version": "0.0.1"
    }
}