api-scout/examples/nestjs-api/users.controller.ts

🔍 Automatically scout, discover and generate beautiful interactive API documentation from your codebase. Supports Express.js, NestJS, FastAPI, Spring Boot with interactive testing and security analysis.

import {
  Controller,
  Get,
  Post,
  Put,
  Delete,
  Body,
  Param,
  Query,
  Headers,
  UseGuards,
  UseInterceptors,
  UsePipes,
  ValidationPipe,
  HttpStatus,
  HttpException
} from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
import { RolesGuard } from '../guards/roles.guard';
import { TransformInterceptor } from '../interceptors/transform.interceptor';
import { CreateUserDto, UpdateUserDto, UserResponseDto } from './dto/user.dto';
import { User } from '../entities/user.entity';

/**
 * Users Controller
 * Handles all user-related HTTP requests
 */
@Controller('api/users')
@UseInterceptors(TransformInterceptor)
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  /**
   * Get all users with pagination
   * Returns a paginated list of users
   */
  @Get()
  async findAll(
    @Query('page') page: number = 1,
    @Query('limit') limit: number = 10,
    @Query('search') search?: string,
    @Query('role') role?: string
  ): Promise<UserResponseDto[]> {
    return this.usersService.findAll({
      page,
      limit,
      search,
      role
    });
  }

  /**
   * Get user by ID
   * Retrieves a specific user by their unique identifier
   */
  @Get(':id')
  async findOne(@Param('id') id: string): Promise<UserResponseDto> {
    const user = await this.usersService.findOne(+id);
    
    if (!user) {
      throw new HttpException('User not found', HttpStatus.NOT_FOUND);
    }
    
    return user;
  }

  /**
   * Create a new user
   * Creates a new user account with validation
   */
  @Post()
  @UseGuards(AuthGuard('jwt'))
  @UsePipes(new ValidationPipe({ transform: true }))
  async create(
    @Body() createUserDto: CreateUserDto,
    @Headers('authorization') auth: string
  ): Promise<UserResponseDto> {
    return this.usersService.create(createUserDto);
  }

  /**
   * Update user information
   * Updates an existing user's data
   */
  @Put(':id')
  @UseGuards(AuthGuard('jwt'), RolesGuard)
  async update(
    @Param('id') id: string,
    @Body() updateUserDto: UpdateUserDto,
    @Headers('x-user-id') userId: string
  ): Promise<UserResponseDto> {
    return this.usersService.update(+id, updateUserDto);
  }

  /**
   * Delete user account
   * Permanently removes a user from the system
   */
  @Delete(':id')
  @UseGuards(AuthGuard('jwt'), RolesGuard)
  async remove(
    @Param('id') id: string,
    @Headers('authorization') auth: string
  ): Promise<{ message: string; deletedId: number }> {
    await this.usersService.remove(+id);
    
    return {
      message: 'User successfully deleted',
      deletedId: +id
    };
  }

  /**
   * Get user's posts
   * Retrieves all posts created by a specific user
   */
  @Get(':id/posts')
  async getUserPosts(
    @Param('id') id: string,
    @Query('status') status: 'published' | 'draft' | 'archived' = 'published',
    @Query('page') page: number = 1,
    @Query('limit') limit: number = 10
  ): Promise<any[]> {
    return this.usersService.getUserPosts(+id, {
      status,
      page,
      limit
    });
  }

  /**
   * Update user avatar
   * Uploads and updates user profile picture
   */
  @Post(':id/avatar')
  @UseGuards(AuthGuard('jwt'))
  async updateAvatar(
    @Param('id') id: string,
    @Body() avatarData: { avatarUrl: string },
    @Headers('content-type') contentType: string
  ): Promise<{ message: string; avatarUrl: string }> {
    const result = await this.usersService.updateAvatar(+id, avatarData.avatarUrl);
    
    return {
      message: 'Avatar updated successfully',
      avatarUrl: result.avatarUrl
    };
  }

  /**
   * Get user statistics
   * Returns various statistics about the user
   */
  @Get(':id/stats')
  @UseGuards(AuthGuard('jwt'))
  async getUserStats(
    @Param('id') id: string,
    @Query('period') period: '7d' | '30d' | '1y' = '30d'
  ): Promise<{
    posts: number;
    comments: number;
    likes: number;
    followers: number;
  }> {
    return this.usersService.getUserStats(+id, period);
  }
}