@nestjs/swagger#ApiForbiddenResponse TypeScript Examples

@Post('subscribe')
    /** Use ThrottlerGuard to limit number of requests from one IP address. Allow max 4 requests in 20 seconds: */
    @UseGuards(ThrottlerGuard)
    @Throttle(4, 20)
    @ApiOperation({ description: 'Post email to subscribe for newsletters' })
    @ApiResponse({
        status: 200,
        type: Boolean,
    })
    @ApiBody({ type: PluginNewsletterSubscription })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async placeSubscription(@Body() input: PluginNewsletterSubscription): Promise<boolean | undefined> {
        const email = input?.email;
        if (!email || !/\S+@\S+\.\S+/.test(email)) {
            throw new HttpException(`Invalid email`, HttpStatus.BAD_REQUEST);
        }

        const hasSubscribed = await getManager().findOne(PluginNewsletter, {
            where: {
                email
            }
        });
        if (hasSubscribed) return true;

        const newsletter = new PluginNewsletter();
        newsletter.email = email;
        await getManager().save(newsletter);
        return true;
    }

@ApiBearerAuth()
  @ApiOperation({ summary: 'Update document type' })
  @ApiOkResponse({ description: 'The document type has been updated successfully' })
  @ApiBadRequestResponse({ description: 'The document type could not be updated' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @UseGuards(AuthGuard(), RolesGuard)
  @Roles(DefaultRole.Admin)
  @Put()
  @HttpCode(HttpStatus.OK)
  updateDocumentType(
    @Body() documentType: DocumentType,
  ): Promise<void> {
    try {
      return this.documentTypeService.upsert(documentType)
    } catch (error) {
      switch (error.code) {
        default:
          this.logger.error(error.message, 'UPDATE_DOCUMENT_TYPE')
          throw new BadRequestException(error.message)
      }
    }
  }

@Post('settings')
    @UseGuards(JwtAuthGuard)
    @Roles('administrator')
    @ApiOperation({
        description: 'Saves JSON settings of a plugin by pluginName.',
        parameters: [{ name: 'pluginName', in: 'query', required: true }]
    })
    @ApiResponse({
        status: 200,
        type: Boolean
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async savePluginSettings(@Query('pluginName') pluginName: string, @Body() input): Promise<boolean> {
        logger.log('PluginController::savePluginSettings');

        if (!pluginName)
            throw new HttpException(`Invalid plugin name: ${pluginName}`, HttpStatus.NOT_ACCEPTABLE);

        return savePluginSettings(pluginName, input);
    }

@Get('entity')
    @UseGuards(JwtAuthGuard)
    @Roles('administrator', 'guest')
    @ApiOperation({
        description: 'Returns DB record of a plugin by pluginName.',
        parameters: [{ name: 'pluginName', in: 'query', required: true }]
    })
    @ApiResponse({
        status: 200,
        type: PluginEntityDto
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async getPluginEntity(@Query('pluginName') pluginName: string): Promise<PluginEntityDto | undefined> {
        logger.log('PluginController::getPluginEntity ' + pluginName);

        if (!pluginName)
            throw new HttpException(`Invalid plugin name: ${pluginName}`, HttpStatus.NOT_ACCEPTABLE);

        return new PluginEntityDto().parse(await findPlugin(pluginName));
    }

@Post('page')
    @UseGuards(JwtAuthGuard)
    @Roles('administrator')
    @ApiOperation({
        description: `Saves page config for specified Page by pageRoute in query param. 
            Modifications (TCromwellBlockData) must contain only newly added mods or an empty array. 
            It is not allowed to send all mods from /theme/page route because they contain mods from 
            theme's config and we don't need to copy them into user's config that way.`,
        parameters: [
            { name: 'themeName', in: 'query', required: true },
        ],
    })
    @ApiResponse({
        status: 200,
        type: Boolean
    })
    @ApiBody({ type: PageConfigDto })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async savePageConfig(@Body() input: PageConfigDto, @Query('themeName') themeName: string): Promise<boolean> {
        logger.log('ThemeController::savePageConfig');
        if (!themeName)
            throw new HttpException('You must provide `themeName` query parameter', HttpStatus.BAD_REQUEST);

        if (input && typeof input === 'object') {
            return await this.themeService.saveUserPageConfig(input, themeName);
        }
        return false;
    }

@Post('palette')
    @UseGuards(JwtAuthGuard)
    @Roles('administrator')
    @ApiOperation({
        description: `Update palette of an active theme`,
        parameters: [
            { name: 'themeName', in: 'query', required: true },
        ],
    })
    @ApiResponse({
        status: 201,
        type: Boolean
    })
    @ApiBody({ type: ThemePaletteDto })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async saveThemePalette(@Body() input: ThemePaletteDto, @Query('themeName') themeName: string): Promise<boolean> {
        logger.log('ThemeController::saveThemePalette');
        if (input && typeof input === 'object') {
            return await this.themeService.saveThemePalette(input, themeName);
        }
        return false;
    }

@Get('plugin-names')
    @ApiOperation({
        description: `Returns array of plugin names at all pages.`,
        parameters: [
            { name: 'themeName', in: 'query', required: true },
        ],
    })
    @ApiResponse({
        status: 200,
        type: [String]
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async getAllPluginNames(@Query('themeName') themeName: string): Promise<string[]> {
        logger.log('ThemeController::getAllPluginNames');
        if (!themeName)
            throw new HttpException('You must provide `themeName` query parameter', HttpStatus.BAD_REQUEST);

        const out: string[] = [];

        const pages = await this.themeService.readAllPageConfigs(themeName);
        pages.forEach(p => {
            p.modifications.forEach(mod => {
                if (mod.type === 'plugin' && mod.plugin && mod.plugin.pluginName && !out.includes(mod.plugin.pluginName)) {
                    out.push(mod.plugin.pluginName);
                }
            })
        });
        return out;
    }

@Get('pages/info')
    @ApiOperation({
        description: `Returns all pages' info without modifications.`,
        parameters: [
            { name: 'themeName', in: 'query', required: true },
        ],
    })
    @ApiResponse({
        status: 200,
        type: PageInfoDto
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async getPagesInfo(@Query('themeName') themeName: string): Promise<TPageInfo[]> {
        logger.log('ThemeController::getPagesInfo');
        if (!themeName)
            throw new HttpException('You must provide `themeName` query parameter', HttpStatus.BAD_REQUEST);

        return this.themeService.getPagesInfo(themeName);
    }

@Get('pages/configs')
    @ApiOperation({
        description: `Returns all pages with merged modifications.`,
        parameters: [
            { name: 'themeName', in: 'query', required: true },
        ],
    })
    @ApiResponse({
        status: 200,
        type: [PageConfigDto]
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async getAllPageConfigs(@Query('themeName') themeName: string): Promise<TPageConfig[]> {
        logger.log('ThemeController::getAllPageConfigs');
        if (!themeName)
            throw new HttpException('You must provide `themeName` query parameter', HttpStatus.BAD_REQUEST);

        return this.themeService.readAllPageConfigs(themeName);
    }

@Get('config')
    @ApiOperation({
        description: `Returns theme's module config from module.config.js.`,
        parameters: [
            { name: 'themeName', in: 'query', required: true },
        ],
    })
    @ApiResponse({
        status: 200,
        type: ThemeConfigDto
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async getThemeConfig(@Query('themeName') themeName: string): Promise<TThemeConfig | null> {
        logger.log('ThemeController::getThemeConfig');
        if (!themeName)
            throw new HttpException('You must provide `themeName` query parameter', HttpStatus.BAD_REQUEST);

        const { themeConfig } = await getThemeConfigs(themeName);
        return new ThemeConfigDto().parse(themeConfig);
    }

@Get('info')
    @ApiOperation({
        description: `Returns theme's info from package.json.`,
        parameters: [
            { name: 'themeName', in: 'query', required: true },
        ],
    })
    @ApiResponse({
        status: 200,
        type: ModuleInfoDto
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async getThemeInfo(@Query('themeName') themeName: string): Promise<TPackageCromwellConfig | null> {
        logger.log('ThemeController::getThemeInfo');
        if (!themeName)
            throw new HttpException('You must provide `themeName` query parameter', HttpStatus.BAD_REQUEST);

        const { themeInfo } = await getThemeConfigs(themeName);
        return themeInfo;
    }

@ApiBearerAuth()
  @ApiOperation({ summary: 'Create document type' })
  @ApiOkResponse({ description: 'The document type has been created successfully' })
  @ApiBadRequestResponse({ description: 'The document type could not be created' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @UseGuards(AuthGuard(), RolesGuard)
  @Roles(DefaultRole.Admin)
  @Post()
  @HttpCode(HttpStatus.OK)
  async addDocumentType(
    @Body() documentType: DocumentType,
  ): Promise<void> {
    try {
      await this.documentTypeService.insert(documentType)
    } catch (error) {
      switch (error.code) {
        default:
          this.logger.error(error.message, 'ADD_DOCUMENT_TYPE')
          throw new BadRequestException(error.message)
      }
    }
  }

@Get('settings')
    @UseGuards(JwtAuthGuard)
    @Roles('administrator', 'guest')
    @ApiOperation({
        description: 'Returns JSON settings of a plugin by pluginName.',
        parameters: [{ name: 'pluginName', in: 'query', required: true }]
    })
    @ApiResponse({
        status: 200,
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async getPluginSettings(@Query('pluginName') pluginName: string): Promise<any | undefined> {
        logger.log('PluginController::getPluginSettings ' + pluginName);

        if (!pluginName)
            throw new HttpException(`Invalid plugin name: ${pluginName}`, HttpStatus.NOT_ACCEPTABLE);

        return getPluginSettings(pluginName);
    }

@ApiBearerAuth()
  @ApiOperation({ summary: 'Delete document type' })
  @ApiOkResponse({ description: 'The document type has been deleted successfully' })
  @ApiBadRequestResponse({ description: 'The document type could not be deleted' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @UseGuards(AuthGuard(), RolesGuard)
  @Roles(DefaultRole.Admin)
  @Delete(':id')
  @HttpCode(HttpStatus.OK)
  async deleteDocumentType(
    @Param('id', ParseIntPipe) id: number
  ): Promise<void> {
    const usersWithDocumentType = await this.userService.countByDocumentTypeId(id)
    if (usersWithDocumentType > 0) {
      throw new BadRequestException(ERRORS.USER_HAS_DOCUMENT_TYPE)
    }
    try {
      await this.documentTypeService.delete(id)
    } catch (error) {
      switch (error.code) {
        default:
          this.logger.error(error.message, 'DELETE_DOCUMENT_TYPE')
          throw new BadRequestException(error.message)
      }
    }
  }

@ApiOperation({ summary: 'Get the list of roles' })
  @ApiOkResponse({ description: 'Role list' })
  @ApiInternalServerErrorResponse({ description: 'Internal Server Error' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @Get()
  @HttpCode(HttpStatus.OK)
  async findAll(): Promise<Role[]> {
    return await this.roleService.findAll()
  }

@ApiOperation({ summary: 'Create a new role' })
  @ApiBody({ type: Role, description: 'Role information' })
  @ApiCreatedResponse({ description: 'The role was created successfully' })
  @ApiBadRequestResponse({ description: 'The role could not be created' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @Post()
  @HttpCode(HttpStatus.CREATED)
  async addRole(
    @Body() role: Role
  ): Promise<void> {
    try {
      await this.roleService.addRole(role)
    } catch (error) {
      /**
       * Validate database exceptions
       */
      switch(error.code) {
        case POSTGRES.UNIQUE_VIOLATION:
          throw new BadRequestException(ERRORS.UNIQUE_VIOLATION)
        default:
          this.logger.error(error.message, 'ADD_ROLE')
          throw new BadRequestException(error.message)
      }
    }
  }

@ApiOperation({ summary: 'Update a role' })
  @ApiBody({ type: Role, description: 'Role information' })
  @ApiOkResponse({ description: 'The role was updated successfully' })
  @ApiBadRequestResponse({ description: 'The role could not be updated' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @Put()
  @HttpCode(HttpStatus.OK)
  async updateRole(
    @Body() role: Role
  ): Promise<void> {
    try {
      await this.roleService.updateRole(role)
    } catch (error) {
      /**
       * Validate database exceptions
       */
      switch(error.code) {
        case POSTGRES.UNIQUE_VIOLATION:
          throw new BadRequestException(ERRORS.UNIQUE_VIOLATION)
        default:
          this.logger.error(error.message, 'UPDATE_ROLE')
          throw new BadRequestException(error.message)
      }
    }
  }

@ApiOperation({ summary: 'Delete a role' })
  @ApiOkResponse({ description: 'Role deleted' })
  @ApiBadRequestResponse({ description: 'The role could not be deleted' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @Delete(':id')
  @HttpCode(HttpStatus.OK)
  async delete(
    @Param('id', ParseIntPipe) id: number
  ): Promise<void> {
    if (id === DefaultRole.User) {
      throw new BadRequestException(ERRORS.ROLE_USER_DELETION)
    } else if (id === DefaultRole.Admin) {
      throw new BadRequestException(ERRORS.ROLE_ADMIN_DELETION)
    }
    try {
      await this.roleService.delete(id)
    } catch (error) {
      this.logger.error(error.message, 'DELETE_ROLE')
      throw new BadRequestException(error.message)
    }
  }

@ApiOperation({ summary: 'Get the info of a user' })
  @ApiNotFoundResponse({ description: 'User not found' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @ApiOkResponse({
    type: User,
    description: 'User information'
  })
  @UseGuards(RolesGuard)
  @Roles(DefaultRole.Admin)
  @Get(':id')
  @HttpCode(HttpStatus.OK)
  async findOne(
    @Param('id') id: string
  ): Promise<User> {
    const user = await this.userService.findOne(id)
    if (user) {
      return user
    } else {
      throw new NotFoundException(ERRORS.USER_NOT_FOUND)
    }
  }

@ApiOperation({ summary: 'Create a user' })
  @ApiBody({ type: User, description: 'User information' })
  @ApiCreatedResponse({ description: 'The user was created successfully' })
  @ApiBadRequestResponse({ description: 'The user could not be created' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @UseGuards(RolesGuard)
  @Roles(DefaultRole.Admin)
  @Post()
  @HttpCode(HttpStatus.CREATED)
  async addUser(
    @Body() user: User
  ): Promise<void> {
    try {
      user.role = new Role({ id: DefaultRole.User })
      await this.userService.addUser(user)
    } catch (error) {
      /**
       * Validate database exceptions
       */
      switch(error.code) {
        case POSTGRES.UNIQUE_VIOLATION:
          throw new BadRequestException(ERRORS.UNIQUE_VIOLATION)
        default:
          this.logger.error(error.message, 'ADD_USER')
          throw new BadRequestException(error.message)
      }
    }
  }

@ApiOperation({ summary: 'Update a user' })
  @ApiBody({ type: User, description: 'User information' })
  @ApiOkResponse({ description: 'The user was updated successfully' })
  @ApiBadRequestResponse({ description: 'The user could not be updated' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @UseGuards(RolesGuard)
  @Roles(DefaultRole.Admin)
  @Put()
  @HttpCode(HttpStatus.OK)
  async updateUser(
    @Body() user: User
  ): Promise<void> {
    try {
      await this.userService.updateUser(user)
    } catch (error) {
      /**
       * Validate database exceptions
       */
      switch(error.code) {
        case POSTGRES.UNIQUE_VIOLATION:
          throw new BadRequestException(ERRORS.UNIQUE_VIOLATION)
        default:
          this.logger.error(error.message, 'UPDATE_USER')
          throw new BadRequestException(error.message)
      }
    }
  }

@ApiOperation({ summary: 'Delete a user' })
  @ApiOkResponse({ description: 'User deleted' })
  @ApiBadRequestResponse({ description: 'The user could not be deleted' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @UseGuards(RolesGuard)
  @Roles(DefaultRole.Admin)
  @Delete(':id')
  @HttpCode(HttpStatus.OK)
  async delete(
    @Param('id') id: string
  ): Promise<void> {
    try {
      await this.userService.deleteById(id)
    } catch (error) {
      this.logger.error(error.message, 'DELETE_USER')
      throw new BadRequestException(error.message)
    }
  }

@ApiOperation({ summary: 'Add new users' })
  @ApiBody({ type: User, isArray: true, description: 'Info of the users' })
  @ApiCreatedResponse({ description: 'The users were created successfully' })
  @ApiBadRequestResponse({ description: 'The users could not be created' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @UseGuards(RolesGuard)
  @Roles(DefaultRole.Admin)
  @Post('bulk')
  @HttpCode(HttpStatus.CREATED)
  async createBulk(
    @Body(new ParseArrayPipe({ items: User })) users: User[]
  ): Promise<void> {
    try {
      await this.userService.addUsers(users)
    } catch (error) {
      /**
       * Validate database exceptions
       */
      switch(error.code) {
        case POSTGRES.UNIQUE_VIOLATION:
          throw new BadRequestException(ERRORS.UNIQUE_VIOLATION)
        default:
          this.logger.error(error.message, 'ADD_USERS')
          throw new BadRequestException(error.message)
      }
    }
  }

/**
   * Login user authentication
   * @param dto User Form
   * @example /auth/login
   */
  @ApiOperation({ summary: 'Login user authentication', description: 'In this way you will get the Token for Bearer authentication' })
  @ApiCreatedResponse({ status: 201, description: 'Login success, you will receive the "accessToken" there' })
  @ApiBadRequestResponse({ status: 400, description: 'Invalid credentials' })
  @ApiForbiddenResponse({ status: 403, description: 'Account is disabled, contact with administrator' })
  @ApiNotFoundResponse({ status: 404, description: 'Your account does not exist' })
  @ApiUnauthorizedResponse({ status: 401, description: 'Unauthorized' })
  @ApiBadGatewayResponse({ status: 502, description: 'Login user authentication' })
  @ApiBody({ type: LoginDto })
  @UseGuards(LocalAuthGuard)
  @Post('auth/login')
  async login(@Request() req, @Body() loginDto: LoginDto) {
    return await this.authService.login(req.user);
  }

@Get('change-theme')
    @UseGuards(JwtAuthGuard)
    @Roles('administrator')
    @ApiOperation({
        description: `Makes specified theme as active one and restarts Renderer`,
        parameters: [{ name: 'themeName', in: 'query', required: true }]
    })
    @ApiResponse({
        status: 200,
        type: Boolean
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async setActiveTheme(@Query('themeName') themeName: string): Promise<boolean> {
        logger.log('CmsController::setActiveTheme');
        if (!themeName)
            throw new HttpException(`Invalid theme name: ${themeName}`, HttpStatus.NOT_ACCEPTABLE);

        return this.themeService.setActive(themeName);
    }

/** 
     * The same method as pluginNewsletterStats in PluginNewsletterResolver. 
     * Added for documentation purposes of custom Controllers.
     * */
    @Get('stats')
    /** You can restrict route by assigning JwtAuthGuard and passing allowed roles as a decorator: */
    @UseGuards(JwtAuthGuard)
    @Roles('administrator', 'guest', 'author')
    @ApiOperation({ description: 'Get newsletters count' })
    @ApiResponse({
        status: 200,
        type: String,
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async getStats(@Request() request: TRequestWithUser): Promise<string> {

        // Or you can retrieve user info and validate permissions in the method:
        const allowedRoles: TUserRole[] = ['administrator', 'guest', 'author'];
        if (!allowedRoles.includes(request.user?.role))
            throw new ForbiddenException('Forbidden');

        return (await getManager().find(PluginNewsletter) ?? []).length + '';
    }

@Get('settings')
    @ApiOperation({ description: 'Returns public CMS settings from DB and cmsconfig.json' })
    @ApiResponse({
        status: 200,
        type: CmsConfigDto,
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async getConfig(): Promise<CmsConfigDto | undefined> {
        // logger.log('CmsController::getConfig');
        const config = await getCmsSettings();
        if (!config) {
            throw new HttpException('CmsController::getConfig Failed to read CMS Config', HttpStatus.INTERNAL_SERVER_ERROR);
        }
        return new CmsConfigDto().parseConfig(config);
    }

@Get('admin-settings')
    @UseGuards(JwtAuthGuard)
    @Roles('administrator', 'guest')
    @ApiOperation({ description: 'Returns admin CMS settings from DB and cmsconfig.json' })
    @ApiResponse({
        status: 200,
        type: AdminCmsConfigDto,
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async getAdminConfig(): Promise<AdminCmsConfigDto | undefined> {
        // logger.log('CmsController::getPrivateConfig');
        return this.cmsService.getAdminConfig();
    }

@Get('themes')
    @UseGuards(JwtAuthGuard)
    @Roles('administrator', 'guest')
    @ApiOperation({ description: 'Returns info from configs of all themes present in "themes" directory' })
    @ApiResponse({
        status: 200,
        type: [ModuleInfoDto],
    })
    @ApiForbiddenResponse({ description: 'Forbidden.' })
    async getThemes(): Promise<TPackageCromwellConfig[] | undefined> {
        logger.log('CmsController::getThemes');
        return this.cmsService.readThemes();
    }