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/search/presentation/controllers/search.controller.ts

@@ -5,6 +5,12 @@ import {
   Query,
   UseGuards,
 } from '@nestjs/common';
+import {
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiBearerAuth,
+} from '@nestjs/swagger';
 import { CommandBus, QueryBus } from '@nestjs/cqrs';
 import { SearchPropertiesQuery } from '../../application/queries/search-properties/search-properties.query';
 import { GeoSearchQuery } from '../../application/queries/geo-search/geo-search.query';
@@ -17,6 +23,7 @@ import { Roles } from '@modules/auth/presentation/decorators/roles.decorator';
 import { type SearchResult } from '../../domain/repositories/search.repository';
 import { type ReindexResult } from '../../application/commands/reindex-all/reindex-all.handler';
 
+@ApiTags('search')
 @Controller('search')
 export class SearchController {
   constructor(
@@ -25,6 +32,8 @@ export class SearchController {
   ) {}
 
   @Get()
+  @ApiOperation({ summary: 'Search properties', description: 'Public full-text and faceted property search' })
+  @ApiResponse({ status: 200, description: 'Search results returned successfully' })
   async search(@Query() dto: SearchPropertiesDto): Promise<SearchResult> {
     return this.queryBus.execute(
       new SearchPropertiesQuery(
@@ -46,6 +55,8 @@ export class SearchController {
   }
 
   @Get('geo')
+  @ApiOperation({ summary: 'Geo search properties', description: 'Public geographic radius property search' })
+  @ApiResponse({ status: 200, description: 'Geo search results returned successfully' })
   async geoSearch(@Query() dto: GeoSearchDto): Promise<SearchResult> {
     return this.queryBus.execute(
       new GeoSearchQuery(
@@ -66,6 +77,11 @@ export class SearchController {
   @UseGuards(JwtAuthGuard, RolesGuard)
   @Roles('ADMIN')
   @Post('reindex')
+  @ApiBearerAuth('JWT')
+  @ApiOperation({ summary: 'Reindex all properties', description: 'Admin-only endpoint to trigger a full reindex' })
+  @ApiResponse({ status: 201, description: 'Reindex completed successfully' })
+  @ApiResponse({ status: 401, description: 'Unauthorized — missing or invalid JWT' })
+  @ApiResponse({ status: 403, description: 'Forbidden — requires ADMIN role' })
   async reindex(): Promise<ReindexResult> {
     return this.commandBus.execute(new ReindexAllCommand());
   }

apps/api/src/modules/search/presentation/dto/geo-search.dto.ts

@@ -8,6 +8,7 @@ import {
   Max,
 } from 'class-validator';
 import { Transform, Type } from 'class-transformer';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 
 export enum GeoSortByOption {
   DISTANCE = 'distance',
@@ -17,48 +18,57 @@ export enum GeoSortByOption {
 }
 
 export class GeoSearchDto {
+  @ApiProperty({ description: 'Latitude of the search center', example: 10.7769, minimum: -90, maximum: 90 })
   @Type(() => Number)
   @IsNumber()
   @Min(-90)
   @Max(90)
   lat!: number;
 
+  @ApiProperty({ description: 'Longitude of the search center', example: 106.7009, minimum: -180, maximum: 180 })
   @Type(() => Number)
   @IsNumber()
   @Min(-180)
   @Max(180)
   lng!: number;
 
+  @ApiProperty({ description: 'Search radius in kilometres', example: 5, minimum: 0.1, maximum: 100 })
   @Type(() => Number)
   @IsNumber()
   @Min(0.1)
   @Max(100)
   radiusKm!: number;
 
+  @ApiPropertyOptional({ description: 'Property type filter', example: 'apartment' })
   @IsOptional()
   @IsString()
   propertyType?: string;
 
+  @ApiPropertyOptional({ description: 'Transaction type filter (sale or rent)', example: 'sale' })
   @IsOptional()
   @IsString()
   transactionType?: string;
 
+  @ApiPropertyOptional({ description: 'Minimum price in VND', example: 1000000000, minimum: 0 })
   @IsOptional()
   @Type(() => Number)
   @IsNumber()
   @Min(0)
   priceMin?: number;
 
+  @ApiPropertyOptional({ description: 'Maximum price in VND', example: 5000000000, minimum: 0 })
   @IsOptional()
   @Type(() => Number)
   @IsNumber()
   @Min(0)
   priceMax?: number;
 
+  @ApiPropertyOptional({ description: 'Sort order', enum: GeoSortByOption, example: GeoSortByOption.DISTANCE })
   @IsOptional()
   @IsEnum(GeoSortByOption)
   sortBy?: GeoSortByOption;
 
+  @ApiPropertyOptional({ description: 'Page number (1-based)', example: 1, default: 1, minimum: 1 })
   @IsOptional()
   @Type(() => Number)
   @IsInt()
@@ -66,6 +76,7 @@ export class GeoSearchDto {
   @Transform(({ value }) => value ?? 1)
   page?: number;
 
+  @ApiPropertyOptional({ description: 'Results per page', example: 20, default: 20, minimum: 1, maximum: 100 })
   @IsOptional()
   @Type(() => Number)
   @IsInt()

apps/api/src/modules/search/presentation/dto/search-properties.dto.ts

@@ -8,6 +8,7 @@ import {
   Max,
 } from 'class-validator';
 import { Transform, Type } from 'class-transformer';
+import { ApiPropertyOptional } from '@nestjs/swagger';
 
 export enum SortByOption {
   PRICE_ASC = 'price_asc',
@@ -17,60 +18,72 @@ export enum SortByOption {
 }
 
 export class SearchPropertiesDto {
+  @ApiPropertyOptional({ description: 'Free-text search query', example: 'chung cu quan 7' })
   @IsOptional()
   @IsString()
   q?: string;
 
+  @ApiPropertyOptional({ description: 'Property type filter', example: 'apartment' })
   @IsOptional()
   @IsString()
   propertyType?: string;
 
+  @ApiPropertyOptional({ description: 'Transaction type filter (sale or rent)', example: 'sale' })
   @IsOptional()
   @IsString()
   transactionType?: string;
 
+  @ApiPropertyOptional({ description: 'Minimum price in VND', example: 1000000000, minimum: 0 })
   @IsOptional()
   @Type(() => Number)
   @IsNumber()
   @Min(0)
   priceMin?: number;
 
+  @ApiPropertyOptional({ description: 'Maximum price in VND', example: 5000000000, minimum: 0 })
   @IsOptional()
   @Type(() => Number)
   @IsNumber()
   @Min(0)
   priceMax?: number;
 
+  @ApiPropertyOptional({ description: 'Minimum area in m²', example: 50, minimum: 0 })
   @IsOptional()
   @Type(() => Number)
   @IsNumber()
   @Min(0)
   areaMin?: number;
 
+  @ApiPropertyOptional({ description: 'Maximum area in m²', example: 200, minimum: 0 })
   @IsOptional()
   @Type(() => Number)
   @IsNumber()
   @Min(0)
   areaMax?: number;
 
+  @ApiPropertyOptional({ description: 'Number of bedrooms', example: 2, minimum: 0 })
   @IsOptional()
   @Type(() => Number)
   @IsInt()
   @Min(0)
   bedrooms?: number;
 
+  @ApiPropertyOptional({ description: 'District name', example: 'Quan 7' })
   @IsOptional()
   @IsString()
   district?: string;
 
+  @ApiPropertyOptional({ description: 'City name', example: 'Ho Chi Minh' })
   @IsOptional()
   @IsString()
   city?: string;
 
+  @ApiPropertyOptional({ description: 'Sort order', enum: SortByOption, example: SortByOption.PRICE_ASC })
   @IsOptional()
   @IsEnum(SortByOption)
   sortBy?: SortByOption;
 
+  @ApiPropertyOptional({ description: 'Page number (1-based)', example: 1, default: 1, minimum: 1 })
   @IsOptional()
   @Type(() => Number)
   @IsInt()
@@ -78,6 +91,7 @@ export class SearchPropertiesDto {
   @Transform(({ value }) => value ?? 1)
   page?: number;
 
+  @ApiPropertyOptional({ description: 'Results per page', example: 20, default: 20, minimum: 1, maximum: 100 })
   @IsOptional()
   @Type(() => Number)
   @IsInt()