Crono API Client Generator

Generador de clientes TypeScript para APIs RESTful basado en especificaciones OpenAPI/Swagger. Desarrollado por Crono API para simplificar la integración con servicios backend.

Características

• ✅ Genera clientes TypeScript completos desde especificaciones OpenAPI/Swagger
• ✅ Crea interfaces TypeScript para todos los modelos de datos con propiedades obligatorias
• ✅ Implementa servicios con métodos tipados para cada endpoint
• ✅ Incluye clase ApiService base con métodos HTTP convenientes
• ✅ Extrae esquemas inline de respuestas API cuando no hay definiciones explícitas
• ✅ Compatible con React, Vue, Angular y otros frameworks frontend

Instalación

# Instalación global
npm install -g crono-api-client-generator

# O como dependencia de desarrollo
npm install --save-dev crono-api-client-generator

Uso rápido

# Ejecuta el generador utilizando el alias principal (recomendado)
npx generate-client --swagger https://api.ejemplo.com/openapi.json

# Ejecuta el generador usando el nombre completo del paquete publicado
npx crono-api-client-generator --swagger https://api.ejemplo.com/openapi.json

# Si tienes el swagger descargado localmente
npx generate-client --swagger ./swagger.json

# Personaliza la URL base por defecto
npx generate-client --swagger ./swagger.json --baseURL "https://api.ejemplo.com"

# Cambia el directorio destino (por defecto se genera en src/services/)
npx generate-client --swagger ./swagger.json --outputDir app/client

Manejo de errores

El generador incluye validación y manejo de errores mejorado:

• Validación de rutas: Verifica que los archivos locales existan antes de intentar procesarlos
• Soporte para URLs y archivos locales: Detecta automáticamente si se trata de una URL o un archivo local
• Mensajes claros: Muestra errores descriptivos con instrucciones para solucionarlos
• Creación automática de directorios: Crea la estructura necesaria si no existe

Solución de problemas comunes

Si encuentras problemas al generar el cliente:

1. Error de acceso a URL: Algunas APIs restringen el acceso a su especificación OpenAPI. Intenta descargar el archivo Swagger manualmente y usar la ruta local.

2. Especificación inválida: Verifica que el archivo JSON/YAML sea una especificación OpenAPI válida.

3. Problemas de red: Si hay errores de conexión, usa un archivo local como alternativa.

Estructura generada

El generador crea la siguiente estructura en tu proyecto:

src/
└── services/
    ├── ApiService.ts       # Clase base con métodos HTTP
    ├── apis.ts             # Exporta todos los servicios generados
    ├── apiModels.ts        # Todas las interfaces en un solo archivo
    └── services.ts         # Implementación de los servicios

Nota: El directorio por defecto es src/services/, pero puedes cambiarlo con --outputDir. Además, la carpeta generada se incluye en .gitignore por defecto, ya que contiene código generado.

Interfaces generadas

Las interfaces generadas siguen el estándar de Crono API, donde todas las propiedades son obligatorias:

// Ejemplo de interfaz generada
export interface INEOperacion {
  CodigoOperacion: string;
  IdOperacion: number;
  Operacion: string;
  CodigoIOE: string;
  Url: string;
  Tablas: number;
}

El generador es capaz de extraer interfaces incluso cuando la API no define esquemas explícitamente, analizando las estructuras de respuesta de cada endpoint.

Uso del cliente generado

// Importa el servicio que necesitas
import { UserService } from './services/apis';
import { User } from './services/apiModels';

// Usa el servicio tipado
async function getUsers() {
  try {
    const users = await UserService.getUsers();
    console.log(users);
    
    // Tipado completo gracias a las interfaces generadas
    const user: User = users[0];
  } catch (error) {
    console.error('Error al obtener usuarios:', error);
  }
}

// O usa ApiService directamente para endpoints personalizados
import { apiService } from './services/ApiService';
import { User } from './services/apiModels';

async function customRequest() {
  const data = await apiService.get<User[]>('/custom/endpoint');
  return data;
}

Personalización

Para personalizar la URL base o agregar interceptores (por ejemplo, para autenticación):

// En tu archivo de configuración
import { apiService } from './services/ApiService';
import axios from 'axios';

// Configura la URL base desde variables de entorno
apiService.api.defaults.baseURL = process.env.API_URL;

// Agrega interceptores para tokens de autenticación
apiService.api.interceptors.request.use(config => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

Mejoras recientes

• Generación directa de archivos: Implementación mejorada que genera archivos directamente sin dependencias intermedias
• Parser de Swagger robusto: Soporte completo para OpenAPI 3.0 y Swagger 2.0
• Extracción de esquemas inline: Capacidad para generar interfaces a partir de respuestas API sin definiciones explícitas
• Propiedades obligatorias: Todas las propiedades en las interfaces generadas son obligatorias por defecto
• Manejo mejorado de errores: Mensajes claros y descriptivos cuando ocurren problemas

Opciones

| Opción | Descripción | Valor por defecto | |--------|-------------|------------------| | --swagger | URL o ruta al archivo de especificación OpenAPI/Swagger | (requerido) | | --spec | Alias para --swagger | - | | --input | Alias para --swagger | - | | --baseURL | URL base para las peticiones API | import.meta.env.VITE_API_BASE_URL | | --outputDir / --dest | Directorio base donde se generará services/ | src |

Licencia

ISC © Crono API