formularios_api/src/seccion/seccion.documentation.ts

import { ApiBody, ApiOperation, ApiParam, ApiResponse, ApiTags } from '@nestjs/swagger';
import { applyDecorators } from '@nestjs/common';

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

  // Documentación para crear una sección
  static ApiCreate = applyDecorators(
    ApiOperation({
      summary: 'Crear una nueva sección',
      description: 'Crea una nueva sección para un cuestionario'
    }),
    ApiBody({
      description: 'Datos de la sección a crear',
      schema: {
        type: 'object',
        required: ['titulo'],
        properties: {
          titulo: { type: 'string', example: 'Información Personal' },
          descripcion: { 
            type: 'string', 
            example: 'Proporciona tus datos personales para poder contactarte'
          },
          contador_pregunta: { type: 'number', example: 0 },
          preguntas: {
            type: 'array',
            items: {
              type: 'object',
              properties: {
                titulo: { type: 'string', example: '¿Eres parte de la comunidad?' },
                obligatoria: { type: 'boolean', example: true },
                tipo: { type: 'string', example: 'Multiple' },
                opciones: {
                  type: 'array',
                  items: {
                    type: 'object',
                    properties: {
                      valor: { type: 'string', example: 'Si' }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }),
    ApiResponse({ 
      status: 201, 
      description: 'Sección creada correctamente',
      schema: {
        type: 'object',
        properties: {
          id_seccion: { type: 'number', example: 1 },
          titulo: { type: 'string', example: 'Información Personal' },
          descripcion: { type: 'string' },
          contador_pregunta: { type: 'number', example: 0 }
        }
      }
    }),
    ApiResponse({ status: 400, description: 'Datos de la sección inválidos' }),
    ApiResponse({ status: 500, description: 'Error interno del servidor' })
  );

  // Documentación para obtener todas las secciones
  static ApiGetAll = applyDecorators(
    ApiOperation({
      summary: 'Obtener todas las secciones',
      description: 'Retorna una lista de todas las secciones registradas'
    }),
    ApiResponse({
      status: 200,
      description: 'Lista de secciones obtenida correctamente',
      schema: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            id_seccion: { type: 'number', example: 1 },
            titulo: { type: 'string', example: 'Información Personal' },
            descripcion: { type: 'string' },
            contador_pregunta: { type: 'number', example: 0 }
          }
        }
      }
    }),
    ApiResponse({ status: 500, description: 'Error interno del servidor' })
  );

  // Documentación para obtener una sección por ID
  static ApiGetOne = applyDecorators(
    ApiOperation({
      summary: 'Obtener una sección por ID',
      description: 'Retorna una sección específica por su ID'
    }),
    ApiParam({
      name: 'id',
      description: 'ID de la sección',
      required: true,
      type: 'number',
      example: 1
    }),
    ApiResponse({
      status: 200,
      description: 'Sección obtenida correctamente',
      schema: {
        type: 'object',
        properties: {
          id_seccion: { type: 'number', example: 1 },
          titulo: { type: 'string', example: 'Información Personal' },
          descripcion: { type: 'string' },
          contador_pregunta: { type: 'number', example: 0 }
        }
      }
    }),
    ApiResponse({ status: 404, description: 'Sección no encontrada' }),
    ApiResponse({ status: 500, description: 'Error interno del servidor' })
  );

  // Documentación para actualizar una sección
  static ApiUpdate = applyDecorators(
    ApiOperation({
      summary: 'Actualizar una sección',
      description: 'Actualiza los datos de una sección existente'
    }),
    ApiParam({
      name: 'id',
      description: 'ID de la sección a actualizar',
      required: true,
      type: 'number',
      example: 1
    }),
    ApiBody({
      description: 'Datos a actualizar de la sección',
      schema: {
        type: 'object',
        properties: {
          titulo: { type: 'string', example: 'Título actualizado' },
          descripcion: { type: 'string', example: 'Descripción actualizada' }
        }
      }
    }),
    ApiResponse({
      status: 200,
      description: 'Sección 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: 'Sección no encontrada' }),
    ApiResponse({ status: 500, description: 'Error interno del servidor' })
  );

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