formularios_api/src/cuestionario/docs/cuestionario.documentation.ts

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' }),
  );
}