fix(backend): Swagger pagination for users list uses concrete response DTO

- Add PaginatedUsersResponseDto with typed UserProfileDto[] for OpenAPI
- Point GET /users @apiresponse type at that class instead of generic PaginatedResponseDto
- Align controller return type with service; add unit assertion for runtime DTO class

Made-with: Cursor

Author: Mimah97

backend/src/users-module/paginated-users-response.dto.ts

@@ -0,0 +1,36 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { UserProfileDto } from './user-profile.dto';
+
+/**
+ * OpenAPI response shape for GET /users (cursor pagination).
+ * Use this class in @ApiResponse({ type: ... }) so Swagger receives a runtime
+ * constructor with a concrete `data` item type (avoid generic-only schemas).
+ */
+export class PaginatedUsersResponseDto {
+  @ApiProperty({ description: 'Users for this page', type: [UserProfileDto] })
+  data: UserProfileDto[];
+
+  @ApiPropertyOptional({
+    description: 'Cursor for next page (last item ID)',
+    nullable: true,
+  })
+  cursor: string | null;
+
+  @ApiProperty({ description: 'Number of items per page' })
+  limit: number;
+
+  @ApiPropertyOptional({ description: 'Cursor token for the next page', nullable: true })
+  nextCursor: string | null;
+
+  @ApiProperty({ description: 'Whether more items exist after this page' })
+  hasMore: boolean;
+
+  @ApiPropertyOptional({ description: 'Total number of matching items (when known)' })
+  total?: number;
+
+  @ApiPropertyOptional({ description: 'Current page number (1-based), page-mode responses' })
+  page?: number;
+
+  @ApiPropertyOptional({ description: 'Total pages, page-mode responses' })
+  totalPages?: number;
+}

backend/src/users-module/users.controller.spec.ts

@@ -3,7 +3,9 @@ import { UsersController } from './users.controller';
 import { UsersService } from './users.service';
 import { CreateUserDto } from './create-user.dto';
 import { UpdateUserDto } from './update-user.dto';
-import { UserProfileDto, PaginationDto } from './user-profile.dto';
+import { UserProfileDto } from './user-profile.dto';
+import { PaginationDto } from '../common/dto';
+import { PaginatedUsersResponseDto } from './paginated-users-response.dto';
 
 const mockProfile = (): UserProfileDto => ({
   id: 'uuid-1',
@@ -40,6 +42,11 @@ describe('UsersController', () => {
     expect(controller).toBeDefined();
   });
 
+  it('uses PaginatedUsersResponseDto as a runtime Swagger response type', () => {
+    expect(typeof PaginatedUsersResponseDto).toBe('function');
+    expect(PaginatedUsersResponseDto.name).toBe('PaginatedUsersResponseDto');
+  });
+
   describe('create', () => {
     it('should create a user and return profile', async () => {
       const dto: CreateUserDto = {

backend/src/users-module/users.controller.ts

@@ -25,10 +25,7 @@ import { CreateUserDto } from './create-user.dto';
 import { UpdateUserDto } from './update-user.dto';
 import { PaginationDto, PaginatedResponseDto } from '../common/dto';
 import { UserProfileDto } from './user-profile.dto';
-
-type PaginatedUsersDto = PaginatedResponseDto<UserProfileDto> & {
-  data: UserProfileDto[];
-};
+import { PaginatedUsersResponseDto } from './paginated-users-response.dto';
 
 @ApiTags('Users')
 @Controller({ path: 'users', version: '1' })
@@ -50,8 +47,14 @@ export class UsersController {
   // GET /users
   @Get()
   @ApiOperation({ summary: 'List all users (paginated)' })
-  @ApiResponse({ status: 200, description: 'Paginated users list', type: PaginatedResponseDto })
-  findAll(@Query() pagination: PaginationDto): Promise<PaginatedUsersDto> {
+  @ApiResponse({
+    status: 200,
+    description: 'Paginated users list (cursor-based)',
+    type: PaginatedUsersResponseDto,
+  })
+  findAll(
+    @Query() pagination: PaginationDto,
+  ): Promise<PaginatedResponseDto<UserProfileDto>> {
     return this.usersService.findAll(pagination);
   }