formularios_api/src/administrador/docs/administrador.documentation.ts

import {
  ApiBearerAuth,
  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 = applyDecorators(ApiTags('Administrador'));
  // 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: {
          nombre_usuario: {
            type: 'string',
            example: 'mike',
            description: 'Nombre de usuario del administrador',
          },
          correo: {
            type: 'string',
            format: 'email',
            example: 'admin@ejemplo.com',
            description: 'Correo electrónico del administrador',
          },
          password: {
            type: 'string',
            format: 'password',
            example: 'password',
            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: 'password',
            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' }),
  );
}