formularios_api/src/pregunta/pregunta.documentation.ts

import { ApiBody, ApiOperation, ApiParam, ApiResponse, ApiTags } from '@nestjs/swagger';
import { applyDecorators } from '@nestjs/common';
import { TipoPreguntaEnum } from './dto/create-pregunta.dto';

export class PreguntaApiDocumentation {
  // Decoradores para toda la clase del controlador
  static ApiController = ApiTags('Preguntas');

  // Documentación para crear una pregunta
  static ApiCreate = applyDecorators(
    ApiOperation({
      summary: 'Crear una nueva pregunta',
      description: 'Crea una nueva pregunta para una sección'
    }),
    ApiBody({
      description: 'Datos de la pregunta a crear',
      schema: {
        type: 'object',
        required: ['titulo', 'tipo'],
        properties: {
          titulo: { type: 'string', example: '¿Eres parte de la comunidad?' },
          obligatoria: { type: 'boolean', example: true },
          tipo: { 
            type: 'string', 
            enum: Object.values(TipoPreguntaEnum),
            description: 'Tipo de pregunta: Cerrada (opción única), Abierta (texto libre), Multiple (varias opciones)',
            example: TipoPreguntaEnum.CERRADA
          },
          contador_opcion: { type: 'number', example: 0 },
          id_opcion_dependiente: { type: 'number', example: null },
          validacion: { 
            type: 'string', 
            description: 'Tipo de validación para la respuesta (cuenta_alumno, correo, telefono, nombre, entero, decimal, etc)', 
            example: 'correo' 
          },
          opciones: {
            type: 'array',
            items: {
              type: 'object',
              properties: {
                valor: { type: 'string', example: 'Si' }
              }
            }
          }
        }
      },
      examples: {
        cerrada: {
          summary: 'Pregunta de opción única',
          value: {
            titulo: '¿Eres parte de la comunidad de la FES Acatlán?',
            obligatoria: true,
            tipo: TipoPreguntaEnum.CERRADA,
            validacion: null,
            opciones: [
              { valor: 'Sí' },
              { valor: 'No' }
            ]
          }
        },
        abierta: {
          summary: 'Pregunta de texto libre',
          value: {
            titulo: '¿Qué mejorarías en nuestro servicio?',
            obligatoria: false,
            tipo: TipoPreguntaEnum.ABIERTA,
            validacion: null
          }
        },
        multiple: {
          summary: 'Pregunta de selección múltiple',
          value: {
            titulo: '¿Qué aspectos del servicio fueron de tu agrado?',
            obligatoria: false,
            tipo: TipoPreguntaEnum.MULTIPLE,
            validacion: null,
            opciones: [
              { valor: 'Rapidez' },
              { valor: 'Atención al cliente' },
              { valor: 'Facilidad de uso' }
            ]
          }
        }
      }
    }),
    ApiResponse({ 
      status: 201, 
      description: 'Pregunta creada correctamente',
      schema: {
        type: 'object',
        properties: {
          id_pregunta: { type: 'number', example: 1 },
          pregunta: { type: 'string', example: '¿Eres parte de la comunidad?' },
          obligatoria: { type: 'boolean', example: true },
          contador_opcion: { type: 'number', example: 0 },
          id_tipo_pregunta: { type: 'number', example: 1 },
          id_opcion_dependiente: { type: 'number', example: null },
          validacion: { type: 'string', example: 'correo' }
        }
      }
    }),
    ApiResponse({ status: 400, description: 'Datos de la pregunta inválidos' }),
    ApiResponse({ status: 500, description: 'Error interno del servidor' })
  );

  // Documentación para obtener todas las preguntas
  static ApiGetAll = applyDecorators(
    ApiOperation({
      summary: 'Obtener todas las preguntas',
      description: 'Retorna una lista de todas las preguntas registradas'
    }),
    ApiResponse({
      status: 200,
      description: 'Lista de preguntas obtenida correctamente',
      schema: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            id_pregunta: { type: 'number', example: 1 },
            pregunta: { type: 'string', example: '¿Eres parte de la comunidad?' },
            obligatoria: { type: 'boolean', example: true },
            contador_opcion: { type: 'number', example: 0 },
            id_tipo_pregunta: { type: 'number', example: 1 },
            id_opcion_dependiente: { type: 'number', example: null },
            validacion: { type: 'string', example: 'correo' }
          }
        }
      }
    }),
    ApiResponse({ status: 500, description: 'Error interno del servidor' })
  );

  // Documentación para obtener una pregunta por ID
  static ApiGetOne = applyDecorators(
    ApiOperation({
      summary: 'Obtener una pregunta por ID',
      description: 'Retorna una pregunta específica por su ID'
    }),
    ApiParam({
      name: 'id',
      description: 'ID de la pregunta',
      required: true,
      type: 'number',
      example: 1
    }),
    ApiResponse({
      status: 200,
      description: 'Pregunta obtenida correctamente',
      schema: {
        type: 'object',
        properties: {
          id_pregunta: { type: 'number', example: 1 },
          pregunta: { type: 'string', example: '¿Eres parte de la comunidad?' },
          obligatoria: { type: 'boolean', example: true },
          contador_opcion: { type: 'number', example: 0 },
          id_tipo_pregunta: { type: 'number', example: 1 },
          id_opcion_dependiente: { type: 'number', example: null },
          validacion: { type: 'string', example: 'correo' },
          opciones: {
            type: 'array',
            items: {
              type: 'object',
              properties: {
                id_opcion: { type: 'number', example: 1 },
                opcion: { type: 'string', example: 'Si' }
              }
            }
          }
        }
      }
    }),
    ApiResponse({ status: 404, description: 'Pregunta no encontrada' }),
    ApiResponse({ status: 500, description: 'Error interno del servidor' })
  );

  // Documentación para actualizar una pregunta
  static ApiUpdate = applyDecorators(
    ApiOperation({
      summary: 'Actualizar una pregunta',
      description: 'Actualiza los datos de una pregunta existente'
    }),
    ApiParam({
      name: 'id',
      description: 'ID de la pregunta a actualizar',
      required: true,
      type: 'number',
      example: 1
    }),
    ApiBody({
      description: 'Datos a actualizar de la pregunta',
      schema: {
        type: 'object',
        properties: {
          pregunta: { type: 'string', example: 'Pregunta actualizada' },
          obligatoria: { type: 'boolean', example: false }
        }
      }
    }),
    ApiResponse({
      status: 200,
      description: 'Pregunta actualizada correctamente',
      schema: {
        type: 'object',
        properties: {
          affected: { type: 'number', example: 1 }
        }
      }
    }),
    ApiResponse({ status: 400, description: 'Datos de actualización inválidos' }),
    ApiResponse({ status: 404, description: 'Pregunta no encontrada' }),
    ApiResponse({ status: 500, description: 'Error interno del servidor' })
  );

  // Documentación para eliminar una pregunta
  static ApiRemove = applyDecorators(
    ApiOperation({
      summary: 'Eliminar una pregunta',
      description: 'Elimina permanentemente una pregunta por su ID'
    }),
    ApiParam({
      name: 'id',
      description: 'ID de la pregunta a eliminar',
      required: true,
      type: 'number',
      example: 1
    }),
    ApiResponse({
      status: 200,
      description: 'Pregunta eliminada correctamente',
      schema: {
        type: 'object',
        properties: {
          affected: { type: 'number', example: 1 }
        }
      }
    }),
    ApiResponse({ status: 404, description: 'Pregunta no encontrada' }),
    ApiResponse({ status: 500, description: 'Error interno del servidor' })
  );
}