formularios_api/src/participante/participante.documentation.ts

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

export class ParticipanteApiDocumentation {
  // Decorador para toda la clase del controlador
  static ApiController = ApiTags('Participantes');

  // Documentación para crear un participante
  static ApiCreate = applyDecorators(
    ApiOperation({
      summary: 'Registrar un nuevo participante',
      description: 'Crea un nuevo registro de participante en el sistema'
    }),
    ApiBody({
      description: 'Datos del participante a registrar',
      schema: {
        type: 'object',
        required: ['correo', 'id_tipo_user'],
        properties: {
          correo: { 
            type: 'string', 
            format: 'email',
            example: 'usuario@ejemplo.com',
            description: 'Correo electrónico del participante' 
          },
          id_tipo_user: { 
            type: 'integer', 
            example: 1,
            description: 'ID del tipo de usuario' 
          }
        }
      }
    }),
    ApiResponse({ 
      status: 201, 
      description: 'Participante registrado exitosamente',
      schema: {
        type: 'object',
        properties: {
          id_participante: { type: 'number', example: 1 },
          correo: { type: 'string', example: 'usuario@ejemplo.com' },
          id_tipo_user: { type: 'number', example: 1 }
        }
      }
    }),
    ApiResponse({ status: 400, description: 'Datos del participante inválidos' }),
    ApiResponse({ status: 409, description: 'El participante ya existe' })
  );

  // Documentación para obtener todos los participantes
  static ApiGetAll = applyDecorators(
    ApiOperation({
      summary: 'Obtener todos los participantes',
      description: 'Retorna una lista de todos los participantes registrados'
    }),
    ApiResponse({
      status: 200,
      description: 'Lista de participantes obtenida correctamente',
      schema: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            id_participante: { type: 'number', example: 1 },
            correo: { type: 'string', example: 'usuario@ejemplo.com' },
            id_tipo_user: { type: 'number', example: 1 },
            tipo_user: {
              type: 'object',
              properties: {
                id_tipo_user: { type: 'number', example: 1 },
                tipo_user: { type: 'string', example: 'Estudiante' }
              }
            },
            participanteEventos: {
              type: 'array',
              items: {
                type: 'object',
                properties: {
                  id_participante_evento: { type: 'number', example: 1 },
                  id_participante: { type: 'number', example: 1 },
                  id_evento: { type: 'number', example: 1 },
                  fecha_inscripcion: { type: 'string', format: 'date-time', example: '2025-04-01T10:00:00Z' },
                  estatus: { type: 'boolean', example: true }
                }
              }
            }
          }
        }
      }
    })
  );

  // Documentación para obtener un participante por ID
  static ApiGetOne = applyDecorators(
    ApiOperation({
      summary: 'Obtener un participante por ID',
      description: 'Retorna los datos de un participante específico según su ID'
    }),
    ApiParam({
      name: 'id',
      description: 'ID del participante',
      type: 'number',
      example: 1
    }),
    ApiResponse({
      status: 200,
      description: 'Participante obtenido correctamente',
      schema: {
        type: 'object',
        properties: {
          id_participante: { type: 'number', example: 1 },
          correo: { type: 'string', example: 'usuario@ejemplo.com' },
          id_tipo_user: { type: 'number', example: 1 },
          tipo_user: {
            type: 'object',
            properties: {
              id_tipo_user: { type: 'number', example: 1 },
              tipo_user: { type: 'string', example: 'Estudiante' }
            }
          },
          participanteEventos: {
            type: 'array',
            items: {
              type: 'object',
              properties: {
                id_participante_evento: { type: 'number', example: 1 },
                id_participante: { type: 'number', example: 1 },
                id_evento: { type: 'number', example: 1 },
                fecha_inscripcion: { type: 'string', format: 'date-time', example: '2025-04-01T10:00:00Z' },
                estatus: { type: 'boolean', example: true }
              }
            }
          }
        }
      }
    }),
    ApiResponse({ status: 404, description: 'Participante no encontrado' })
  );

  // Documentación para actualizar un participante
  static ApiUpdate = applyDecorators(
    ApiOperation({
      summary: 'Actualizar datos de un participante',
      description: 'Actualiza la información de un participante existente'
    }),
    ApiParam({
      name: 'id',
      description: 'ID del participante a actualizar',
      type: 'number',
      example: 1
    }),
    ApiBody({
      description: 'Datos a actualizar del participante',
      schema: {
        type: 'object',
        properties: {
          correo: { 
            type: 'string', 
            format: 'email',
            example: 'nuevo_correo@ejemplo.com',
            description: 'Nuevo correo electrónico del participante' 
          },
          id_tipo_user: { 
            type: 'integer', 
            example: 2,
            description: 'Nuevo tipo de usuario' 
          }
        }
      }
    }),
    ApiResponse({
      status: 200,
      description: 'Participante actualizado correctamente',
      schema: {
        type: 'object',
        properties: {
          id_participante: { type: 'number', example: 1 },
          correo: { type: 'string', example: 'nuevo_correo@ejemplo.com' },
          id_tipo_user: { type: 'number', example: 2 }
        }
      }
    }),
    ApiResponse({ status: 400, description: 'Datos de actualización inválidos' }),
    ApiResponse({ status: 404, description: 'Participante no encontrado' })
  );

  // Documentación para eliminar un participante
  static ApiRemove = applyDecorators(
    ApiOperation({
      summary: 'Eliminar un participante',
      description: 'Elimina permanentemente un participante por su ID'
    }),
    ApiParam({
      name: 'id',
      description: 'ID del participante a eliminar',
      type: 'number',
      example: 1
    }),
    ApiResponse({
      status: 200,
      description: 'Participante eliminado correctamente',
      schema: {
        type: 'object',
        properties: {
          affected: { type: 'number', example: 1 }
        }
      }
    }),
    ApiResponse({ status: 404, description: 'Participante no encontrado' })
  );
}