routing-controllers

Follow these steps to set up a basic RESTful API using routing-controllers and Express.

1. Define a controller class using decorators like @Controller, @Get, @Post, @Param, and @Body.
2. Initialize the server using createExpressServer and pass the controllers in the configuration object.
3. Start the server using the standard .listen() method.

import { createExpressServer } from 'routing-controllers';
import { Controller, Param, Body, Get, Post, Put, Delete } from 'routing-controllers';

@Controller()
export class UserController {
  @Get('/users')
  getAll() {
    return 'This action returns all users';
  }

  @Get('/users/:id')
  getOne(@Param('id') id: number) {
    return 'This action returns user #' + id;
  }

  @Post('/users')
  post(@Body() user: any) {
    return 'Saving user...';
  }

  @Put('/users/:id')
  put(@Param('id') id: number, @Body() user: any) {
    return 'Updating a user...';
  }

  @Delete('/users/:id')
  remove(@Param('id') id: number) {
    return 'Removing user...';
  }
}

const app = createExpressServer({
  controllers: [UserController],
});

app.listen(3000);

You can create controller classes with methods as actions that handle requests. routing-controllers will automatically register these routes in your Express or Koa server.

1. Define a controller using decorators like @Controller, @Get, @Post, etc.
2. Use createExpressServer to instantiate the app and register your controllers.
3. Start the server using the returned Express instance.

import 'reflect-metadata';
import { createExpressServer } from 'routing-controllers';
import { Controller, Param, Body, Get, Post, Put, Delete } from 'routing-controllers';

@Controller()
export class UserController {
  @Get('/users')
  getAll() {
    return 'This action returns all users';
  }

  @Get('/users/:id')
  getOne(@Param('id') id: number) {
    return 'This action returns user #' + id;
  }

  @Post('/users')
  post(@Body() user: any) {
    return 'Saving user...';
  }

  @Put('/users/:id')
  put(@Param('id') id: number, @Body() user: any) {
    return 'Updating a user...';
  }

  @Delete('/users/:id')
  remove(@Param('id') id: number) {
    return 'Removing user...';
  }
}

const app = createExpressServer({
  controllers: [UserController],
});

app.listen(3000);

You can create controllers using classes and decorators, then register them using createExpressServer (for Express) or createKoaServer (for Koa).

Note: You must import reflect-metadata at the very beginning of your application entry point.

// 1. Define a Controller (UserController.ts)
import { Controller, Param, Body, Get, Post, Put, Delete } from 'routing-controllers';

@Controller()
export class UserController {
  @Get('/users')
  getAll() {
    return 'This action returns all users';
  }

  @Get('/users/:id')
  getOne(@Param('id') id: number) {
    return 'This action returns user #' + id;
  }

  @Post('/users')
  post(@Body() user: any) {
    return 'Saving user...';
  }

  @Put('/users/:id')
  put(@Param('id') id: number, @Body() user: any) {
    return 'Updating a user...';
  }

  @Delete('/users/:id')
  remove(@Param('id') id: number) {
    return 'Removing user...';
  }
}

// 2. Create the Server (app.ts)
import 'reflect-metadata';
import { createExpressServer } from 'routing-controllers';
import { UserController } from './UserController';

const app = createExpressServer({
  controllers: [UserController],
});

app.listen(3000);

By default, routing-controllers uses class-transformer to instantiate classes when parsing request data (e.g., @Body, @Param, @QueryParam).

If you specify a class type in your method signature, routing-controllers will create an actual instance of that class rather than a plain literal object. This allows you to use class methods on the parsed data.

• To enable: Set classTransformer: true in createExpressServer (this is the default behavior).
• To disable: Set classTransformer: false in createExpressServer.

import { createExpressServer, Controller, Body } from 'routing-controllers';

class User {
  firstName: string;
  lastName: string;
  getName(): string {
    return this.lastName + ' ' + this.firstName;
  }
}

@Controller()
export class UserController {
  @Post("/")
  post(@Body() user: User) {
    // 'user' is an instance of User, so getName() is available
    console.log('saving user ' + user.getName());
  }
}

createExpressServer({
  classTransformer: true,
  controllers: [UserController],
}).listen(3000);

You can inject services into controllers, middlewares, and error handlers by setting up a DI container during application bootstrap using useContainer.

When using typedi, ensure you decorate your Controllers with @Service() so the container can instantiate them.

For other IoC providers (like inversify), implement the IocAdapter interface and pass it to useContainer.

// Example with TypeDI
import { createExpressServer, useContainer } from 'routing-controllers';
import { Container } from 'typedi';
import path from 'path';

useContainer(Container);

createExpressServer({
  controllers: [path.join(__dirname, '/controllers/*.js')],
  middlewares: [path.join(__dirname, '/middlewares/*.js')],
  interceptors: [path.join(__dirname, '/interceptors/*.js')],
}).listen(3000);

@Controller()
@Service()
export class UsersController {
  constructor(private userRepository: UserRepository) {}
}

Interceptors allow you to modify or replace the data returned by a controller action. You can use them per-action via @UseInterceptor, per-controller, or globally via the @Interceptor decorator.

Interceptor function

Pass a function directly to @UseInterceptor. The function receives the action and the content (the original return value).

Interceptor class

Implement the InterceptorInterface and use the intercept(action: Action, content: any) method to return the transformed content.

// Function Interceptor
@Get("/users")
@UseInterceptor(function(action: Action, content: any) {
    return content.replace(/Mike/gi, "Michael");
})
getOne() {
    return "Hello, I am Mike!";
}

// Class Interceptor
import { Interceptor, InterceptorInterface, Action } from 'routing-controllers';

export class NameCorrectionInterceptor implements InterceptorInterface {
  intercept(action: Action, content: any) {
    return content.replace(/Mike/gi, 'Michael');
  }
}

@UseInterceptor(NameCorrectionInterceptor)
@Get("/users")
getOne() {
    return "Hello, I am Mike!";
}

By default, routing-controllers integrates with class-validator to automatically validate action parameters. If a parameter does not satisfy the decorators defined on its class, a 400 Bad Request is returned with a detailed validation errors array.

• Global Disable: Pass validation: false to createExpressServer.
• Local Enable: Use the validate: true option within a parameter decorator (e.g., @Body({ validate: true })).
• Supported Decorators: This works with @Body, @Param, @QueryParam, @BodyParam, and others.
• Custom Options: You can pass global validation config via createExpressServer({ validation: ... }) or local settings via @Body({ validate: localOptions }).

import { createExpressServer } from 'routing-controllers';

// Disable validation globally
createExpressServer({
  validation: false,
}).listen(3000);

// Enable validation locally for a specific parameter
@Post("/login")
login(@Body({ validate: true }) user: User) {}

// Example User class with class-validator decorators
export class User {
  @IsEmail()
  email: string;

  @MinLength(6)
  password: string;
}