import { ApiBody, ApiOperation, ApiParam, ApiResponse, ApiTags, getSchemaPath, } from '@nestjs/swagger'; import { feriaSexualidad } from '../../../utils/crear_formulario_feria'; import { applyDecorators } from '@nestjs/common'; import { FormularioDto } from '../dto/formulario.schema'; import { CreateCuestionarioDto, CreateCuestionarioEventoDto, } from '../dto/create-cuestionario.dto'; import { ejemploCuestionarioAlumno } from './cuestionario.examples'; export class CuestionarioApiDocumentation { // Decoradores para toda la clase del controlador static ApiController = ApiTags('Cuestionario'); static ApiCreate = applyDecorators( ApiOperation({ summary: 'Crear un nuevo cuestionario para un evento existente', description: 'Este endpoint crea un cuestionario con sus secciones, preguntas y opciones. Se debe proporcionar el ID de un evento existente para asociarlo.', }), ApiBody({ type: CreateCuestionarioDto, examples: { comunidad_estudiantil: ejemploCuestionarioAlumno, }, }), ); // Documentación para obtener el formulario completo static ApiGetFormulario = applyDecorators( ApiOperation({ summary: 'Obtener formulario completo', description: 'Devuelve el cuestionario completo con la misma estructura que se usa para crearlo, incluyendo el atributo validacion para las preguntas que tengan reglas de validación específicas', }), ApiParam({ name: 'id', description: 'ID del cuestionario', required: true, type: 'number', example: 1, }), ApiResponse({ status: 200, description: 'Formulario completo con todas sus secciones, preguntas y opciones. Las preguntas incluyen el atributo "validacion" si tienen reglas de validación específicas (como "correo", "cuenta_alumno", "telefono", "nombre", etc.)', type: FormularioDto, content: { 'application/json': { schema: { $ref: getSchemaPath(FormularioDto) }, example: feriaSexualidad, }, }, }), ApiResponse({ status: 404, description: 'Cuestionario no encontrado' }), ); static ApiCreateWithEvento = applyDecorators( ApiOperation({ summary: 'Crear un nuevo cuestionario con nuevo evento', description: 'Este endpoint crea un cuestionario y también un evento (si no existe) usando el nombre proporcionado. No se requiere `id_evento`, sólo `evento` (nombre del evento, es opcional).', }), ApiResponse({ status: 201, description: 'Cuestionario y evento creados exitosamente', }), ApiResponse({ status: 400, description: 'Datos inválidos', }), ApiBody({ type: CreateCuestionarioEventoDto, examples: { ejemplo_con_evento_nuevo: { summary: 'Cuestionario que crea evento automáticamente', value: { nombre_form: 'Registro de participantes', descripcion: 'Formulario para inscripción de asistentes.', evento: 'Foro Juvenil de Tecnología 2025', fecha_inicio: '2025-07-20T10:00:00', fecha_fin: '2025-07-20T17:00:00', id_tipo_cuestionario: 2, secciones: [ { titulo: 'Datos generales', descripcion: 'Recopilación de información personal', preguntas: [ { titulo: '¿Cuál es tu edad?', tipo: 'Abierta', obligatoria: true, }, { titulo: '¿Cómo te enteraste del evento?', tipo: 'Multiple', opciones: [ { valor: 'Redes sociales' }, { valor: 'Correo electrónico' }, { valor: 'Por un amigo' }, ], }, ], }, ], }, }, }, }), ); // Documentación para obtener todos los cuestionarios static ApiGetAll = applyDecorators( ApiOperation({ summary: 'Obtener todos los cuestionarios', description: 'Retorna una lista de todos los cuestionarios registrados', }), ApiResponse({ status: 200, description: 'Lista de cuestionarios obtenida correctamente', schema: { type: 'array', items: { type: 'object', properties: { id_cuestionario: { type: 'number', example: 1 }, nombre_form: { type: 'string', example: 'Registro para la Feria de la Sexualidad - FES Acatlán', }, descripcion: { type: 'string' }, contador_secciones: { type: 'number', example: 1 }, editable: { type: 'boolean', example: true }, fecha_fin: { type: 'string', format: 'date-time' }, fecha_inicio: { type: 'string', format: 'date-time' }, id_tipo_cuestionario: { type: 'number', example: 1 }, }, }, }, }), ApiResponse({ status: 500, description: 'Error interno del servidor' }), ); // Documentación para obtener un cuestionario por ID static ApiGetOne = applyDecorators( ApiOperation({ summary: 'Obtener un cuestionario por ID', description: 'Retorna un cuestionario específico por su ID', }), ApiParam({ name: 'id', description: 'ID del cuestionario', required: true, type: 'number', example: 1, }), ApiResponse({ status: 200, description: 'Cuestionario obtenido correctamente', schema: { type: 'object', properties: { id_cuestionario: { type: 'number', example: 1 }, nombre_form: { type: 'string', example: 'Registro para la Feria de la Sexualidad - FES Acatlán', }, descripcion: { type: 'string' }, contador_secciones: { type: 'number', example: 1 }, editable: { type: 'boolean', example: true }, fecha_fin: { type: 'string', format: 'date-time' }, fecha_inicio: { type: 'string', format: 'date-time' }, id_tipo_cuestionario: { type: 'number', example: 1 }, }, }, }), ApiResponse({ status: 404, description: 'Cuestionario no encontrado' }), ApiResponse({ status: 500, description: 'Error interno del servidor' }), ); // Documentación para actualizar un cuestionario static ApiUpdate = applyDecorators( ApiOperation({ summary: 'Actualizar un cuestionario', description: 'Actualiza los datos de un cuestionario existente', }), ApiParam({ name: 'id', description: 'ID del cuestionario a actualizar', required: true, type: 'number', example: 1, }), ApiBody({ description: 'Datos a actualizar del cuestionario', schema: { type: 'object', properties: { nombre_form: { type: 'string', example: 'Nombre actualizado del formulario', }, descripcion: { type: 'string', example: 'Descripción actualizada' }, fecha_inicio: { type: 'string', format: 'date-time' }, fecha_fin: { type: 'string', format: 'date-time' }, editable: { type: 'boolean', example: true }, }, }, }), ApiResponse({ status: 200, description: 'Cuestionario actualizado correctamente', schema: { type: 'object', properties: { affected: { type: 'number', example: 1 }, }, }, }), ApiResponse({ status: 400, description: 'Datos de actualización inválidos', }), ApiResponse({ status: 404, description: 'Cuestionario no encontrado' }), ApiResponse({ status: 500, description: 'Error interno del servidor' }), ); // Documentación para eliminar un cuestionario static ApiRemove = applyDecorators( ApiOperation({ summary: 'Eliminar un cuestionario', description: 'Elimina permanentemente un cuestionario por su ID', }), ApiParam({ name: 'id', description: 'ID del cuestionario a eliminar', required: true, type: 'number', example: 1, }), ApiResponse({ status: 200, description: 'Cuestionario eliminado correctamente', schema: { type: 'object', properties: { affected: { type: 'number', example: 1 }, }, }, }), ApiResponse({ status: 404, description: 'Cuestionario no encontrado' }), ApiResponse({ status: 500, description: 'Error interno del servidor' }), ); }