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());
   }