Controllers

Controllers are responsible for handling incoming requests and returning responses to the client. They are the entry points for the application and are used to define routes and request handling logic.

Routing

Controllers are defined using the @Controller decorator. The decorator takes a path argument that defines the base route for all routes defined in the controller.

import { Controller, Get } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
import { Controllers } from 'vitnode-backend/helpers/controller.decorator';
 

@Controllers({

  plugin_name: 'Welcome',

  plugin_code: 'welcome',

  route: 'example',

})
export class ExampleWelcomeController {
  @Get()
  getHello(): string {
    return 'Hello World!';
  }
}

In the example above, the ExampleWelcomeController class is decorated with @CControllers. This means that all routes defined in the controller will be prefixed with /{your_plugin_code}/example.

Enable methods for handling HTTP requests by using the @Get(), @Post(), @Put(), @Delete(), @Patch(), @Options(), and @Head() decorators. These decorators are provided by the @nestjs/common package.

Nesting routes

You can nest routes by using the @Controller() decorator with a route argument. For example we want to create a nested route /{your_plugin_code}/example:

@Controllers({
  plugin_name: 'Welcome',
  plugin_code: 'welcome',

  route: 'example/nested',
})

Disable protecting per route

To disable authorization for a specific route, you can use the @OptionalAuth() decorator.

import { OptionalAuth } from 'vitnode-backend/guards/auth.guard';
 
export class ExampleWelcomeController {
  @Get()
  @OptionalAuth() 
  getHello(@CurrentUser() user?: User): string {
    return `Hello ${user.name}!`;
  }
}

Import into module

To use the controller, import it into the module where it will be used. Go to the module root of your plugin. That's should be apps/backend/src/plugins/{your_plugin_code}/{your_plugin_code}.module.ts. Import the controller and add it to the controllers array.

import { Module } from '@nestjs/common';
import { ExampleWelcomeController } from './example.controller'; 
 
@Module({
  controllers: [ExampleWelcomeController], 
})
export class WelcomeModule {}

Request & Response objects

Controllers can access the request and response objects by using the @Req() and @Res() decorators. These decorators are provided by the @nestjs/common package.

import { Controller, Get, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express'; 
 
@Controller('welcome/example')
export class ExampleWelcomeController {
  @Get()

  getHello(@Req() req: Request, @Res() res: Response): string {
    return 'Hello World!';
  }
}

Operations

OpenAPI operations provide additional information about the operation. You can write documentation API automatically and validate the request.

Responses

Responses are used to define the responses that are returned by the operation. They are defined using the @ApiResponse() decorator.

import { ApiResponse } from '@nestjs/swagger'; 
import { Controllers } from 'vitnode-backend/helpers/controller.decorator';
 
@Controllers({
  plugin_name: 'Welcome',
  plugin_code: 'welcome',
  route: 'example',
})
export class ExampleWelcomeController {
  @Get()
  @ApiResponse({ status: 200, description: 'Hello World!' }) 
  getHello(): string {
    return 'Hello World!';
  }
}

You can use build-in responses like:

import { ApiOkResponse } from '@nestjs/swagger'; 
import { Controllers } from 'vitnode-backend/helpers/controller.decorator';
 
@Controllers({
  plugin_name: 'Welcome',
  plugin_code: 'welcome',
  route: 'example',
})
export class ExampleWelcomeController {
  @Get()
  @ApiOkResponse({ description: 'Hello World!' }) 
  getHello(): string {
    return 'Hello World!';
  }
}

Responses with DTO

You can use DTO to define the response. This is useful when you want to return a complex object and show the structure of the response in the Swagger documentation.

import { ApiOkResponse } from '@nestjs/swagger';
import { Controllers } from 'vitnode-backend/helpers/controller.decorator';
import { ExampleResponseObj } from 'shared/plugins/{your_plugin_code}/example.dto'; 
 
@Controllers({
  plugin_name: 'Welcome',
  plugin_code: 'welcome',
  route: 'example',
})
export class ExampleWelcomeController {
  @Get()
  @ApiOkResponse({ type: ExampleResponseObj }) 
  getHello(): ExampleResponseObj {
    return { message: 'Hello World!' };
  }
}