feat: swagger document endpoints

packages/server/src/modules/Roles/Roles.application.ts

@@ -66,7 +66,7 @@ export class RolesApplication {
    * Gets the role permissions schema.
    * @returns The role permissions schema.
    */
-  async getRolePermissionsSchema() {
+  getRolePermissionsSchema() {
     return this.getRolePermissionsSchemaService.getRolePermissionsSchema();
   }
 }

packages/server/src/modules/Roles/Roles.controller.ts

@@ -19,10 +19,14 @@ import {
   ApiResponse,
   ApiParam,
   ApiBody,
+  getSchemaPath,
+  ApiExtraModels,
 } from '@nestjs/swagger';
+import { RoleResponseDto } from './dtos/RoleResponse.dto';
 
 @ApiTags('Roles')
 @Controller('roles')
+@ApiExtraModels(RoleResponseDto)
 export class RolesController {
   constructor(private readonly rolesApp: RolesApplication) {}
 
@@ -88,14 +92,21 @@ export class RolesController {
     description: 'Role permissions schema',
   })
   async getRolePermissionsSchema() {
-    const schema = await this.rolesApp.getRolePermissionsSchema();
+    const schema = this.rolesApp.getRolePermissionsSchema();
 
     return schema;
   }
 
   @Get()
   @ApiOperation({ summary: 'Get all roles' })
-  @ApiResponse({ status: HttpStatus.OK, description: 'List of all roles' })
+  @ApiResponse({
+    status: HttpStatus.OK,
+    description: 'List of all roles',
+    schema: {
+      type: 'array',
+      items: { $ref: getSchemaPath(RoleResponseDto) },
+    },
+  })
   async getRoles() {
     const roles = await this.rolesApp.getRoles();
 
@@ -105,7 +116,13 @@ export class RolesController {
   @Get(':id')
   @ApiOperation({ summary: 'Get a specific role by ID' })
   @ApiParam({ name: 'id', description: 'Role ID' })
-  @ApiResponse({ status: HttpStatus.OK, description: 'Role details' })
+  @ApiResponse({
+    status: HttpStatus.OK,
+    description: 'Role details',
+    schema: {
+      $ref: getSchemaPath(RoleResponseDto),
+    },
+  })
   async getRole(@Param('id', ParseIntPipe) roleId: number) {
     const role = await this.rolesApp.getRole(roleId);
 

packages/server/src/modules/Roles/dtos/RoleResponse.dto.ts

@@ -0,0 +1,67 @@
+import { ApiProperty, ApiExtraModels } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+
+// RolePermissionResponseDto
+export class RolePermissionResponseDto {
+  @ApiProperty({
+    example: 'read',
+    description: 'The action/ability of the permission',
+  })
+  ability: string;
+
+  @ApiProperty({
+    example: 'item',
+    description: 'The subject of the permission',
+  })
+  subject: string;
+
+  @ApiProperty({
+    example: true,
+    description: 'The value of the permission',
+  })
+  value: boolean;
+}
+
+@ApiExtraModels(RolePermissionResponseDto)
+export class RoleResponseDto {
+  @ApiProperty({
+    example: 1,
+    description: 'Unique identifier of the role',
+  })
+  id: number;
+
+  @ApiProperty({
+    example: 'admin',
+    description: 'The slug of the role',
+  })
+  slug: string;
+
+  @ApiProperty({
+    example: 'Administrator',
+    description: 'The name of the role',
+  })
+  name: string;
+
+  @ApiProperty({
+    example: 'Administrator role with all permissions',
+    description: 'The description of the role',
+  })
+  description: string;
+
+  @ApiProperty({
+    example: false,
+    description: 'Indicates if the role is predefined',
+  })
+  predefined: boolean;
+
+  @ApiProperty({
+    type: [RolePermissionResponseDto],
+    description: 'List of permissions associated with the role',
+    example: [
+      { ability: 'read', subject: 'item', value: true },
+      { ability: 'edit', subject: 'item', value: false },
+    ],
+  })
+  @Type(() => RolePermissionResponseDto)
+  permissions: RolePermissionResponseDto[];
+}