formularios_api/src/administrador/administrador.documentation.ts

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

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

  // Documentación para crear un administrador
  static ApiCreate = applyDecorators(
    ApiOperation({
      summary: 'Registrar un nuevo administrador',
      description: 'Crea un nuevo administrador con correo, contraseña y tipo de administrador'
    }),
    ApiBody({
      description: 'Datos del administrador a registrar',
      schema: {
        type: 'object',
        required: ['correo', 'password', 'id_tipo_user'],
        properties: {
          correo: { 
            type: 'string', 
            format: 'email',
            example: 'admin@ejemplo.com',
            description: 'Correo electrónico del administrador' 
          },
          password: { 
            type: 'string', 
            format: 'password',
            example: 'Password123',
            description: 'Contraseña del administrador (mínimo 6 caracteres)' 
          },
          id_tipo_user: { 
            type: 'integer', 
            example: 1,
            description: 'ID del tipo de usuario administrador' 
          }
        }
      }
    }),
    ApiResponse({ 
      status: 201, 
      description: 'Administrador registrado exitosamente',
      schema: {
        type: 'object',
        properties: {
          id_admnistrador: { type: 'number', example: 1 },
          correo: { type: 'string', example: 'admin@ejemplo.com' },
          id_tipo_user: { type: 'number', example: 1 }
        }
      }
    }),
    ApiResponse({ status: 400, description: 'Datos del administrador inválidos' }),
    ApiResponse({ status: 409, description: 'El correo ya está registrado' })
  );

  // Documentación para iniciar sesión
  static ApiLogin = applyDecorators(
    ApiOperation({
      summary: 'Iniciar sesión como administrador',
      description: 'Autentica un administrador con correo y contraseña, y devuelve un token JWT'
    }),
    ApiBody({
      description: 'Credenciales de inicio de sesión',
      schema: {
        type: 'object',
        required: ['correo', 'password'],
        properties: {
          correo: { 
            type: 'string', 
            format: 'email',
            example: 'admin@ejemplo.com',
            description: 'Correo electrónico del administrador' 
          },
          password: { 
            type: 'string', 
            format: 'password',
            example: 'Password123',
            description: 'Contraseña del administrador' 
          }
        }
      }
    }),
    ApiResponse({ 
      status: 200, 
      description: 'Inicio de sesión exitoso',
      schema: {
        type: 'object',
        properties: {
          access_token: { 
            type: 'string', 
            example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
            description: 'Token JWT para autenticación' 
          },
          id_administrador: { 
            type: 'number', 
            example: 1,
            description: 'ID del administrador autenticado' 
          },
          correo: { 
            type: 'string', 
            example: 'admin@ejemplo.com',
            description: 'Correo del administrador autenticado' 
          },
          tipo_user: { 
            type: 'number', 
            example: 1,
            description: 'Tipo de usuario del administrador' 
          }
        }
      }
    }),
    ApiResponse({ status: 401, description: 'Credenciales inválidas' })
  );

  // Documentación para obtener todos los administradores
  static ApiGetAll = applyDecorators(
    ApiOperation({
      summary: 'Obtener todos los administradores',
      description: 'Retorna una lista de todos los administradores registrados (requiere autenticación)'
    }),
    ApiResponse({
      status: 200,
      description: 'Lista de administradores obtenida correctamente',
      schema: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            id_admnistrador: { type: 'number', example: 1 },
            correo: { type: 'string', example: 'admin@ejemplo.com' },
            id_tipo_user: { type: 'number', example: 1 },
            tipoUser: {
              type: 'array',
              items: {
                type: 'object',
                properties: {
                  id_tipo_user: { type: 'number', example: 1 },
                  tipo_user: { type: 'string', example: 'Administrador General' }
                }
              }
            }
          }
        }
      }
    }),
    ApiResponse({ status: 401, description: 'No autorizado' })
  );

  // Documentación para obtener un administrador por ID
  static ApiGetOne = applyDecorators(
    ApiOperation({
      summary: 'Obtener un administrador por ID',
      description: 'Retorna los datos de un administrador específico según su ID (requiere autenticación)'
    }),
    ApiParam({
      name: 'id',
      description: 'ID del administrador',
      type: 'number',
      example: 1
    }),
    ApiResponse({
      status: 200,
      description: 'Administrador obtenido correctamente',
      schema: {
        type: 'object',
        properties: {
          id_admnistrador: { type: 'number', example: 1 },
          correo: { type: 'string', example: 'admin@ejemplo.com' },
          id_tipo_user: { type: 'number', example: 1 },
          tipoUser: {
            type: 'array',
            items: {
              type: 'object',
              properties: {
                id_tipo_user: { type: 'number', example: 1 },
                tipo_user: { type: 'string', example: 'Administrador General' }
              }
            }
          }
        }
      }
    }),
    ApiResponse({ status: 404, description: 'Administrador no encontrado' }),
    ApiResponse({ status: 401, description: 'No autorizado' })
  );

  // Documentación para actualizar un administrador
  static ApiUpdate = applyDecorators(
    ApiOperation({
      summary: 'Actualizar datos de un administrador',
      description: 'Actualiza la información de un administrador existente (requiere autenticación)'
    }),
    ApiParam({
      name: 'id',
      description: 'ID del administrador a actualizar',
      type: 'number',
      example: 1
    }),
    ApiBody({
      description: 'Datos a actualizar del administrador',
      schema: {
        type: 'object',
        properties: {
          correo: { 
            type: 'string', 
            format: 'email',
            example: 'nuevo_admin@ejemplo.com',
            description: 'Nuevo correo electrónico del administrador' 
          },
          password: { 
            type: 'string', 
            format: 'password',
            example: 'NuevaPassword123',
            description: 'Nueva contraseña del administrador (mínimo 6 caracteres)' 
          },
          id_tipo_user: { 
            type: 'integer', 
            example: 2,
            description: 'Nuevo tipo de usuario administrador' 
          }
        }
      }
    }),
    ApiResponse({
      status: 200,
      description: 'Administrador actualizado correctamente',
      schema: {
        type: 'object',
        properties: {
          id_admnistrador: { type: 'number', example: 1 },
          correo: { type: 'string', example: 'nuevo_admin@ejemplo.com' },
          id_tipo_user: { type: 'number', example: 2 }
        }
      }
    }),
    ApiResponse({ status: 400, description: 'Datos de actualización inválidos' }),
    ApiResponse({ status: 404, description: 'Administrador no encontrado' }),
    ApiResponse({ status: 401, description: 'No autorizado' })
  );

  // Documentación para cambiar contraseña
  static ApiChangePassword = applyDecorators(
    ApiOperation({
      summary: 'Cambiar contraseña de un administrador',
      description: 'Permite a un administrador cambiar su contraseña verificando primero la contraseña actual (requiere autenticación)'
    }),
    ApiParam({
      name: 'id',
      description: 'ID del administrador',
      type: 'number',
      example: 1
    }),
    ApiBody({
      description: 'Datos para cambio de contraseña',
      schema: {
        type: 'object',
        required: ['currentPassword', 'newPassword'],
        properties: {
          currentPassword: { 
            type: 'string', 
            format: 'password',
            example: 'Password123',
            description: 'Contraseña actual del administrador' 
          },
          newPassword: { 
            type: 'string', 
            format: 'password',
            example: 'NuevaPassword123',
            description: 'Nueva contraseña del administrador (mínimo 6 caracteres)' 
          }
        }
      }
    }),
    ApiResponse({
      status: 200,
      description: 'Contraseña actualizada correctamente',
      schema: {
        type: 'object',
        properties: {
          message: { type: 'string', example: 'Contraseña actualizada correctamente' }
        }
      }
    }),
    ApiResponse({ status: 400, description: 'Contraseña actual incorrecta' }),
    ApiResponse({ status: 404, description: 'Administrador no encontrado' }),
    ApiResponse({ status: 401, description: 'No autorizado' })
  );

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