formularios_api/src/pregunta/pregunta.documentation.ts

import {
  ApiBody,
  ApiOperation,
  ApiParam,
  ApiResponse,
  ApiTags,
} from '@nestjs/swagger';
import { applyDecorators } from '@nestjs/common';
import { TipoPreguntaEnum } from 'src/tipo_pregunta/entities/tipo_pregunta.entity';

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