@studiohyperdrive/swagger-express-ts

Register API endpoints and operations using TypeScript Decorators and generate Swagger Documentation automatically for your express application.

Table of contents

• Getting Started
• Usage

Getting Started

Install the package

# NPM
npm install --save @studiohyperdrive/swagger-express-ts

# Yarn
yarn add --save @studiohyperdrive/swagger-express-ts

Usage

See the demo folder for a working example.

1. Create a router for your api:

import {
	ApiPath,
	Router,
} from '@studiohyperdrive/swagger-express-ts';

@ApiPath({
	path: '/demo',
	version: 1,
	description: 'Demo api',
})
class DemoV1Router extends Router {}

2. Add some definitions:

import {
	ApiDefinition,
	SwaggerApiDefinitionProperties,
	SwaggerModelType,
} from '@studiohyperdrive/swagger-express-ts';

...
class DemoV1Router {
  @ApiDefinition({
		type: SwaggerModelType.OBJECT,
		description: 'Thing',
	})
	public static Thing: SwaggerApiDefinitionProperties = {
		count: {
			type: SwaggerModelType.NUMBER,
			description: 'count',
			required: true,
			example: 10,
		},
	};

	@ApiDefinition({
		type: SwaggerModelType.OBJECT,
		description: 'Item',
	})
	public static Item: SwaggerApiDefinitionProperties = {
		foo: {
			type: SwaggerModelType.STRING,
			description: 'bar',
			required: true,
			example: 'stuff and things',
		},
		thing: {
			type: SwaggerModelType.OBJECT,
			model: 'Thing',
			example: {},
		},
	};
}

3. Register an operation:

import {
	ApiOperationGet,
	SwaggerResponseType,
	SwaggerUtils,
} from '@studiohyperdrive/swagger-express-ts';

...
class DemoV1Router {
	@ApiOperationGet({
		description: 'Get all items',
		responses: {
			200: {
				description: 'OK',
				type: SwaggerResponseType.ARRAY,
				model: 'Item'
			},
		},
	})
	public getItems(app: Application): void {
		app.route(this.baseUrl).get(
			SwaggerUtils.createController((req, res, next) => {
				return {
					total: 1,
					pages: 1,
					page: 1,
					size: 20,
					items: [{
						foo: 'bar',
						thing: {
						  count: 2,
						},
					}],
				};
			})
		);
	}
}

4. Use the middleware to serve your docs

import express from 'express';
import { swaggerExpress } from '@studiohyperdrive/swagger-express-ts';

const app = express();

app.use(swaggerExpress({
	docsPath: '/docs',
	basePath: '/',
	info: {
		version: '1.0.0',
		title: 'My custom API',
	},
	host: 'localhost:3000',
	uiOptions: {
		customFavIcon: 'https://link.to.my/favicon.ico',
	},
}));

The docs will be available on the url you configured. For the example above that would be:

# [host]/[docsPath]

http://localhost:3000/docs

You can filter endpoints by API version:

# [host]/[docsPath]/[version]

http://localhost:3000/docs/v1

Or view the swagger spec as a json file:

# [host]/[docsPath]/json

http://localhost:3000/docs/json

Decorators

There are 7 decorators you can use:

• @ApiDefinition: register a Swagger schema
• @ApiPath: register a new API base path
• @ApiOperationGet: register a GET operation
• @ApiOperationPost: register a POST operation
• @ApiOperationPut: register a PUT operation
• @ApiOperationPatch: register a PATCH operation
• @ApiOperationDelete: register a DELETE operation

Utils

createController

The createController util has 2 main functions:

1. Wrap your controller in a try/catch block and properly handle errors.
2. Remove the boilerplate of returning data.

import { Request, Response, Next, SwaggerUtils } from '@studiohyperdrive/swagger-express-ts';

const controller = async (req: Request, res: Response, next: Next): Promise<Items> => {
	return await fetchThings(req.params);
};

SwaggerUtils.createController(controller);

Any value you return will be send back to the client as a JSON response with status 200. Errors will be handled by the global error handling.

extractVersion

The extractVersion util can be used to extract the version (number) from a number or string input:

import { SwaggerUtils } from '@studiohyperdrive';

SwaggerUtils.extractVersion(1); // = 1
SwaggerUtils.extractVersion('1'); // = 1
SwaggerUtils.extractVersion('v1'); // = 1
SwaggerUtils.extractVersion(); // = null
SwaggerUtils.extractVersion('test'); // = null

getBaseUrl

The getBaseUrl util can be used to get a base url from a path and/or version input:

import { SwaggerUtils } from '@studiohyperdrive';

SwaggerUtils.getBaseUrl({ version: 1, path: '/demo' }); // = /v1/demo
SwaggerUtils.getBaseUrl({ path: '/demo' }); // = /demo
SwaggerUtils.getBaseUrl({ version: 'test', path: '/demo' }); // = /demo

paginated

The paginated util can be used to get a paginated Swagger response:

import { SwaggerUtils } from '@studiohyperdrive';

SwaggerUtils.paginated('Item', 'Item description');

{
	description: 'Paginated result',
	type: 'object',
	properties: {
		items: {
			model: 'Item',
			description: 'Item description',
			type: 'array',
		},
		total: {
			type: 'number,
			required: true,
			example: 76,
		},
		pages: {
			type: 'number,
			required: true,
			example: 4,
		},
		page: {
			type: 'number,
			required: true,
			example: 1,
		},
		size: {
			type: 'number,
			required: true,
			example: 20,
		},
	}
}