feat(api): add OpenAPI/Swagger documentation for all API endpoints

Install @nestjs/swagger, configure Swagger UI at /api/docs with JWT bearer
auth, and add ApiTags/ApiOperation/ApiResponse/ApiProperty decorators to
all 8 controllers (50+ endpoints) and 31 DTOs across auth, listings,
search, payments, subscriptions, admin, notifications, and analytics modules.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

apps/api/src/modules/auth/presentation/controllers/auth.controller.ts

@@ -6,6 +6,7 @@ import {
   Post,
   UseGuards,
 } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiResponse, ApiBearerAuth, ApiBody } from '@nestjs/swagger';
 import { CommandBus, QueryBus } from '@nestjs/cqrs';
 import { RegisterUserCommand } from '../../application/commands/register-user/register-user.command';
 import { LoginUserCommand } from '../../application/commands/login-user/login-user.command';
@@ -14,6 +15,7 @@ import { VerifyKycCommand } from '../../application/commands/verify-kyc/verify-k
 import { GetProfileQuery } from '../../application/queries/get-profile/get-profile.query';
 import { GetAgentByUserIdQuery } from '../../application/queries/get-agent-by-user-id/get-agent-by-user-id.query';
 import { RegisterDto } from '../dto/register.dto';
+import { LoginDto } from '../dto/login.dto';
 import { RefreshTokenDto } from '../dto/refresh-token.dto';
 import { VerifyKycDto } from '../dto/verify-kyc.dto';
 import { JwtAuthGuard } from '../guards/jwt-auth.guard';
@@ -25,6 +27,7 @@ import { type JwtPayload, type TokenPair } from '../../infrastructure/services/t
 import { type UserProfileDto } from '../../application/queries/get-profile/get-profile.handler';
 import { type AgentDto } from '../../application/queries/get-agent-by-user-id/get-agent-by-user-id.handler';
 
+@ApiTags('auth')
 @Controller('auth')
 export class AuthController {
   constructor(
@@ -33,6 +36,10 @@ export class AuthController {
   ) {}
 
   @Post('register')
+  @ApiOperation({ summary: 'Register a new user' })
+  @ApiResponse({ status: 201, description: 'User registered, tokens returned' })
+  @ApiResponse({ status: 400, description: 'Validation error' })
+  @ApiResponse({ status: 409, description: 'Phone already registered' })
   async register(@Body() dto: RegisterDto): Promise<TokenPair> {
     return this.commandBus.execute(
       new RegisterUserCommand(dto.phone, dto.password, dto.fullName, dto.email),
@@ -41,6 +48,10 @@ export class AuthController {
 
   @UseGuards(LocalAuthGuard)
   @Post('login')
+  @ApiOperation({ summary: 'Login with phone and password' })
+  @ApiBody({ type: LoginDto })
+  @ApiResponse({ status: 201, description: 'Login successful, tokens returned' })
+  @ApiResponse({ status: 401, description: 'Invalid credentials' })
   async login(@CurrentUser() user: { id: string; phone: string; role: string }): Promise<TokenPair> {
     return this.commandBus.execute(
       new LoginUserCommand(user.id, user.phone, user.role),
@@ -48,18 +59,29 @@ export class AuthController {
   }
 
   @Post('refresh')
+  @ApiOperation({ summary: 'Refresh access token' })
+  @ApiResponse({ status: 201, description: 'New token pair returned' })
+  @ApiResponse({ status: 401, description: 'Invalid or expired refresh token' })
   async refresh(@Body() dto: RefreshTokenDto): Promise<TokenPair> {
     return this.commandBus.execute(new RefreshTokenCommand(dto.refreshToken));
   }
 
   @UseGuards(JwtAuthGuard)
   @Get('profile')
+  @ApiBearerAuth('JWT')
+  @ApiOperation({ summary: 'Get current user profile' })
+  @ApiResponse({ status: 200, description: 'User profile returned' })
+  @ApiResponse({ status: 401, description: 'Unauthorized' })
   async getProfile(@CurrentUser() user: JwtPayload): Promise<UserProfileDto> {
     return this.queryBus.execute(new GetProfileQuery(user.sub));
   }
 
   @UseGuards(JwtAuthGuard)
   @Get('profile/agent')
+  @ApiBearerAuth('JWT')
+  @ApiOperation({ summary: 'Get agent profile for current user' })
+  @ApiResponse({ status: 200, description: 'Agent profile returned (null if not an agent)' })
+  @ApiResponse({ status: 401, description: 'Unauthorized' })
   async getAgentProfile(@CurrentUser() user: JwtPayload): Promise<AgentDto | null> {
     return this.queryBus.execute(new GetAgentByUserIdQuery(user.sub));
   }
@@ -67,6 +89,11 @@ export class AuthController {
   @UseGuards(JwtAuthGuard, RolesGuard)
   @Roles('ADMIN')
   @Patch('kyc')
+  @ApiBearerAuth('JWT')
+  @ApiOperation({ summary: 'Verify user KYC (admin only)' })
+  @ApiResponse({ status: 200, description: 'KYC status updated' })
+  @ApiResponse({ status: 401, description: 'Unauthorized' })
+  @ApiResponse({ status: 403, description: 'Forbidden — admin only' })
   async verifyKyc(
     @Body() dto: VerifyKycDto & { userId: string },
   ): Promise<{ message: string }> {

apps/api/src/modules/auth/presentation/dto/login.dto.ts

@@ -1,9 +1,12 @@
 import { IsString } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
 
 export class LoginDto {
+  @ApiProperty({ example: '0901234567' })
   @IsString()
   phone!: string;
 
+  @ApiProperty({ example: 'P@ssw0rd!' })
   @IsString()
   password!: string;
 }

apps/api/src/modules/auth/presentation/dto/refresh-token.dto.ts

@@ -1,6 +1,8 @@
 import { IsString } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
 
 export class RefreshTokenDto {
+  @ApiProperty({ description: 'JWT refresh token' })
   @IsString()
   refreshToken!: string;
 }

apps/api/src/modules/auth/presentation/dto/register.dto.ts

@@ -1,17 +1,22 @@
 import { IsString, IsOptional, IsEmail, MinLength } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 
 export class RegisterDto {
+  @ApiProperty({ example: '0901234567', description: 'Phone number' })
   @IsString()
   phone!: string;
 
+  @ApiProperty({ example: 'P@ssw0rd!', minLength: 8 })
   @IsString()
   @MinLength(8)
   password!: string;
 
+  @ApiProperty({ example: 'Nguyen Van A' })
   @IsString()
   @MinLength(1)
   fullName!: string;
 
+  @ApiPropertyOptional({ example: 'user@example.com' })
   @IsOptional()
   @IsEmail()
   email?: string;

apps/api/src/modules/auth/presentation/dto/verify-kyc.dto.ts

@@ -1,10 +1,13 @@
 import { IsEnum, IsOptional, IsObject } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { KYCStatus } from '@prisma/client';
 
 export class VerifyKycDto {
+  @ApiProperty({ enum: KYCStatus, description: 'New KYC status' })
   @IsEnum(KYCStatus)
   kycStatus!: KYCStatus;
 
+  @ApiPropertyOptional({ description: 'Additional KYC verification data' })
   @IsOptional()
   @IsObject()
   kycData?: Record<string, unknown>;