Merge pull request #28 from No-Country-simulation/docs/project

feat: enhance API documentation with Swagger annotations for various entities and controllers

Author: CoraYako

Backend/app-talen-backend/src/modules/assessment/application/dto/generate-tests-request.dto.ts

@@ -1,6 +1,11 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
 import { IsOptional, IsString } from 'class-validator';
 
 export class GenerateTestsRequestDto {
+  @ApiPropertyOptional({
+    description: 'Identificador opcional del perfil para generar tests.',
+    example: 'c4b4e87a-c7f8-4cf8-a855-637b6a4b57e1',
+  })
   @IsOptional()
   @IsString()
   profileId?: string;

Backend/app-talen-backend/src/modules/assessment/application/dto/generated-tests-response.dto.ts

@@ -1,24 +1,86 @@
-import { AssessmentTestQuestion } from '../../domain/assessment-test-question.type';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { AssessmentTestType } from '../../domain/assessment-test-type.enum';
 
-export interface GeneratedTest {
-  id: string;
-  name: string;
-  description: string;
-  type: AssessmentTestType;
+export class AssessmentQuestionOptionDto {
+  @ApiProperty({ example: 'a' })
+  value!: string;
+
+  @ApiProperty({ example: 'GET' })
+  label!: string;
+}
+
+export class AssessmentTestQuestionDto {
+  @ApiProperty({ example: 'tech_api_1' })
+  id!: string;
+
+  @ApiProperty({
+    example: 'Que metodo HTTP se usa normalmente para crear un recurso?',
+  })
+  text!: string;
+
+  @ApiProperty({ example: 'api_design' })
+  category!: string;
+
+  @ApiProperty({ example: 'single_choice' })
+  type!: 'single_choice';
+
+  @ApiProperty({ type: () => AssessmentQuestionOptionDto, isArray: true })
+  options!: AssessmentQuestionOptionDto[];
+}
+
+export class GeneratedTest {
+  @ApiProperty({ example: 'psycho_test_1' })
+  id!: string;
+
+  @ApiProperty({ example: 'Test Psicotecnico - Aptitud General' })
+  name!: string;
+
+  @ApiProperty({
+    example:
+      'Evaluacion de razonamiento logico, atencion, toma de decisiones y trabajo en equipo.',
+  })
+  description!: string;
+
+  @ApiProperty({
+    enum: AssessmentTestType,
+    example: AssessmentTestType.PSYCHOTECHNICAL,
+  })
+  type!: AssessmentTestType;
+
+  @ApiPropertyOptional({ example: 'Frontend', nullable: true })
   skillName?: string;
-  questionCount: number;
-  estimatedDurationMin: number;
-  questions: AssessmentTestQuestion[];
+
+  @ApiProperty({ example: 5 })
+  questionCount!: number;
+
+  @ApiProperty({ example: 10 })
+  estimatedDurationMin!: number;
+
+  @ApiProperty({ type: () => AssessmentTestQuestionDto, isArray: true })
+  questions!: AssessmentTestQuestionDto[];
+}
+
+export class GeneratedTestsProfileDto {
+  @ApiProperty({ example: 'Ada Lovelace' })
+  fullName!: string;
+
+  @ApiProperty({ example: 4 })
+  technicalSkillsCount!: number;
+
+  @ApiProperty({ example: 20 })
+  totalQuestionsCount!: number;
 }
 
 export class GeneratedTestsResponseDto {
+  @ApiProperty({ type: () => GeneratedTest, isArray: true })
   psychotechnicalTests!: GeneratedTest[];
+
+  @ApiProperty({ type: () => GeneratedTest, isArray: true })
   technicalTests!: GeneratedTest[];
+
+  @ApiProperty({ example: 3 })
   totalTests!: number;
-  profile!: {
-    fullName: string;
-    technicalSkillsCount: number;
-    totalQuestionsCount: number;
-  };
+
+  @ApiProperty({ type: () => GeneratedTestsProfileDto })
+  profile!: GeneratedTestsProfileDto;
 }

Backend/app-talen-backend/src/modules/assessment/application/dto/submit-assessment-test.dto.ts

@@ -1,6 +1,15 @@
+import { ApiProperty } from '@nestjs/swagger';
 import { IsObject } from 'class-validator';
 
 export class SubmitAssessmentTestDto {
+  @ApiProperty({
+    description:
+      'Mapa de respuestas del test, donde la clave es el identificador de la pregunta.',
+    example: {
+      psy_logic_1: 'b',
+      psy_attention_1: 'a',
+    },
+  })
   @IsObject()
   answers!: Record<string, string>;
 }

Backend/app-talen-backend/src/modules/assessment/infrastructure/assessment.controller.ts

@@ -5,16 +5,22 @@ import { AssessmentService } from '../application/assessment.service';
 import { CreateAssessmentTestDto } from '../application/dto/create-assessment-test.dto';
 import { CreateAssessmentDto } from '../application/dto/create-assessment.dto';
 import { SubmitAssessmentTestDto } from '../application/dto/submit-assessment-test.dto';
-import { GeneratedTestsResponseDto } from '../application/dto/generated-tests-response.dto';
+import {
+  AssessmentTestQuestionDto,
+  GeneratedTestsResponseDto,
+} from '../application/dto/generated-tests-response.dto';
 import { AssessmentTestQuestion } from '../domain/assessment-test-question.type';
 import { AssessmentTestResultEntity } from './entities/assessment-test-result.entity';
 import { Assessment } from './entities/assessment.entity';
 import {
   ApiBearerAuth,
   ApiBody,
+  ApiBadRequestResponse,
+  ApiForbiddenResponse,
   ApiOperation,
   ApiResponse,
   ApiTags,
+  ApiUnauthorizedResponse,
 } from '@nestjs/swagger';
 
 @ApiTags('Evaluaciones')
@@ -33,6 +39,11 @@ export class AssessmentController {
     type: CreateAssessmentDto,
     description: 'Datos para crear la evaluación.',
   })
+  @ApiBadRequestResponse({ description: 'Datos de evaluación inválidos.' })
+  @ApiUnauthorizedResponse({ description: 'Token inválido o ausente.' })
+  @ApiForbiddenResponse({
+    description: 'Solo usuarios TALENT pueden crear evaluaciones.',
+  })
   @ApiResponse({
     status: 201,
     description: 'Evaluación creada.',
@@ -56,6 +67,10 @@ export class AssessmentController {
     description: 'Lista de evaluaciones.',
     type: [Assessment],
   })
+  @ApiUnauthorizedResponse({ description: 'Token inválido o ausente.' })
+  @ApiForbiddenResponse({
+    description: 'Solo usuarios TALENT pueden listar evaluaciones.',
+  })
   findMine(@Req() request: AuthenticatedRequest): Promise<Assessment[]> {
     return this.assessmentService.findMine(request.user);
   }
@@ -71,6 +86,10 @@ export class AssessmentController {
     description: 'Última evaluación.',
     type: Assessment,
   })
+  @ApiUnauthorizedResponse({ description: 'Token inválido o ausente.' })
+  @ApiForbiddenResponse({
+    description: 'Solo usuarios TALENT pueden consultar evaluaciones.',
+  })
   findMyLatest(@Req() request: AuthenticatedRequest): Promise<Assessment> {
     return this.assessmentService.findMyLatest(request.user);
   }
@@ -86,6 +105,10 @@ export class AssessmentController {
     description: 'Evaluacion consolidada creada.',
     type: Assessment,
   })
+  @ApiUnauthorizedResponse({ description: 'Token inválido o ausente.' })
+  @ApiForbiddenResponse({
+    description: 'Solo usuarios TALENT pueden consolidar evaluaciones.',
+  })
   consolidateMyAssessment(
     @Req() request: AuthenticatedRequest,
   ): Promise<Assessment> {
@@ -100,7 +123,11 @@ export class AssessmentController {
   @ApiResponse({
     status: 200,
     description: 'Preguntas del test psicotécnico.',
-    type: [Object],
+    type: [AssessmentTestQuestionDto],
+  })
+  @ApiUnauthorizedResponse({ description: 'Token inválido o ausente.' })
+  @ApiForbiddenResponse({
+    description: 'Solo usuarios TALENT pueden consultar preguntas.',
   })
   getPsychotechnicalQuestions(): AssessmentTestQuestion[] {
     return this.assessmentService.getPsychotechnicalQuestions();
@@ -116,6 +143,10 @@ export class AssessmentController {
     description: 'Tests generados exitosamente.',
     type: GeneratedTestsResponseDto,
   })
+  @ApiUnauthorizedResponse({ description: 'Token inválido o ausente.' })
+  @ApiForbiddenResponse({
+    description: 'Solo usuarios TALENT pueden generar tests.',
+  })
   async generateTestsForProfile(
     @Req() request: AuthenticatedRequest,
   ): Promise<GeneratedTestsResponseDto> {
@@ -130,7 +161,11 @@ export class AssessmentController {
   @ApiResponse({
     status: 200,
     description: 'Preguntas del test técnico.',
-    type: [Object],
+    type: [AssessmentTestQuestionDto],
+  })
+  @ApiUnauthorizedResponse({ description: 'Token inválido o ausente.' })
+  @ApiForbiddenResponse({
+    description: 'Solo usuarios TALENT pueden consultar preguntas.',
   })
   getTechnicalQuestions(): AssessmentTestQuestion[] {
     return this.assessmentService.getTechnicalQuestions();
@@ -146,6 +181,13 @@ export class AssessmentController {
     type: SubmitAssessmentTestDto,
     description: 'Respuestas del test psicotécnico.',
   })
+  @ApiBadRequestResponse({
+    description: 'Respuestas del test psicotécnico inválidas.',
+  })
+  @ApiUnauthorizedResponse({ description: 'Token inválido o ausente.' })
+  @ApiForbiddenResponse({
+    description: 'Solo usuarios TALENT pueden enviar resultados de tests.',
+  })
   @ApiResponse({
     status: 201,
     description: 'Resultado del test psicotécnico.',
@@ -194,6 +236,13 @@ export class AssessmentController {
     type: CreateAssessmentTestDto,
     description: 'Datos del resultado del test psicotécnico.',
   })
+  @ApiBadRequestResponse({
+    description: 'Resultado del test psicotécnico inválido.',
+  })
+  @ApiUnauthorizedResponse({ description: 'Token inválido o ausente.' })
+  @ApiForbiddenResponse({
+    description: 'Solo usuarios TALENT pueden crear resultados.',
+  })
   @ApiResponse({
     status: 201,
     description: 'Resultado creado.',

Backend/app-talen-backend/src/modules/auth/application/dto/external-profile.dto.ts

@@ -1,8 +1,39 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
 export class ExternalProfileDto {
+  @ApiProperty({
+    description: 'Identificador del proveedor externo.',
+    example: 'google-oauth2|1234567890',
+  })
   providerId!: string;
+
+  @ApiProperty({
+    description: 'Correo electrónico del perfil externo.',
+    example: 'talent@example.com',
+  })
   email!: string;
+
+  @ApiProperty({
+    description: 'Nombre del usuario.',
+    example: 'Ada',
+  })
   firstName!: string;
+
+  @ApiProperty({
+    description: 'Apellido del usuario.',
+    example: 'Lovelace',
+  })
   lastName!: string;
+
+  @ApiPropertyOptional({
+    description: 'URL de la imagen del perfil externo.',
+    example: 'https://example.com/avatar.png',
+  })
   picture?: string;
+
+  @ApiPropertyOptional({
+    description: 'Rol inferido o asignado al usuario externo.',
+    example: 'TALENT',
+  })
   role?: string;
 }

Backend/app-talen-backend/src/modules/auth/application/types/auth-response.type.ts

@@ -1,8 +1,29 @@
+import { ApiProperty } from '@nestjs/swagger';
 import { AuthenticatedUser } from '../../domain/authenticated-user.type';
 
-export type AuthResponse = {
-  accessToken: string;
-  tokenType: 'Bearer';
-  expiresIn: string;
-  user: AuthenticatedUser;
-};
+export class AuthResponse {
+  @ApiProperty({
+    description: 'Token JWT emitido por el backend.',
+    example:
+      'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJyb2xlIjoiVEFMRU5UIiwiaWF0IjoxNzE2MDAwMDAwLCJleHAiOjE3MTY1OTQ4MDB9.example-signature',
+  })
+  accessToken!: string;
+
+  @ApiProperty({
+    description: 'Tipo de token utilizado en el encabezado Authorization.',
+    example: 'Bearer',
+  })
+  tokenType!: 'Bearer';
+
+  @ApiProperty({
+    description: 'Tiempo de expiración configurado para el token.',
+    example: '7d',
+  })
+  expiresIn!: string;
+
+  @ApiProperty({
+    description: 'Usuario autenticado asociado al token.',
+    type: () => AuthenticatedUser,
+  })
+  user!: AuthenticatedUser;
+}

Backend/app-talen-backend/src/modules/auth/domain/authenticated-user.type.ts

@@ -1,7 +1,24 @@
+import { ApiProperty } from '@nestjs/swagger';
 import { UserRole } from '../../users/domain/user-role.enum';
 
-export type AuthenticatedUser = {
-  id: string;
-  email: string;
-  role: UserRole;
-};
+export class AuthenticatedUser {
+  @ApiProperty({
+    description: 'Identificador único del usuario.',
+    format: 'uuid',
+    example: '550e8400-e29b-41d4-a716-446655440000',
+  })
+  id!: string;
+
+  @ApiProperty({
+    description: 'Correo electrónico del usuario autenticado.',
+    example: 'talent@example.com',
+  })
+  email!: string;
+
+  @ApiProperty({
+    description: 'Rol asignado al usuario autenticado.',
+    enum: UserRole,
+    example: UserRole.TALENT,
+  })
+  role!: UserRole;
+}