Cómo Generar Clientes API con OpenAPI

Resumen rápido (lectores con prisa)

Qué es: Producción automática de clientes TypeScript/Angular desde una spec OpenAPI.

Cuándo usarlo: Siempre que frontend y backend evolucionen en paralelo y quieras una única fuente de verdad para la API.

Por qué importa: Evita errores por desalineación, asegura tipado fiel y facilita detección temprana de breaking changes en CI.

Cómo funciona: Una CLI genera modelos, servicios y módulos Angular a partir de un JSON/YAML OpenAPI; se integra con Dependency Injection y HttpClient.

Generación de clientes API OpenAPI para Angular: por qué importa

En equipos paralelos, el frontend comienza antes que el backend y viceversa. Sin una fuente de verdad única, los cambios sutiles (un campo renombrado, una paginación distinta) provocan bugs que no se detectan hasta producción.

Beneficios técnicos

Fuentes útiles

Herramientas recomendadas

– OpenAPI Generator (recomendado para empresas): maduro, configurable y soportado por la comunidad.

– ng-openapi-gen: más idiomático para Angular, menos configurable.

– Orval: buena opción si trabajas multi-framework (React/Vue + Angular).

Recomendación práctica: usa OpenAPI Generator si buscas control y estabilidad a largo plazo.

Flujo mínimo práctico con OpenAPI Generator

1. Exporta o publica tu spec en JSON/YAML (p. ej. /swagger.json).
2. Añade la CLI como devDependency:

npm install -D @openapitools/openapi-generator-cli

3. Configura un archivo (infra-as-code), ejemplo openapitools.json:

{
  "generator-cli": {
    "generators": {
      "v1": {
        "generatorName": "typescript-angular",
        "inputSpec": "api-specs/openapi.json",
        "output": "src/app/core/api/v1",
        "additionalProperties": {
          "ngVersion": "16.0",
          "fileNaming": "kebab-case",
          "stringEnums": true
        }
      }
    }
  }
}

4. Añade script en package.json:

"scripts": {
  "api:generate": "openapi-generator-cli generate"
}

5. Ejecuta npm run api:generate. Resultado: src/app/core/api/v1 con models/, services/ y api.module.ts.

Integración en Angular (ejemplo)

Configura el módulo generado en tu AppModule/CoreModule:

import { ApiModule, Configuration } from './core/api/v1';
@NgModule({
  imports: [
    ApiModule.forRoot(() => new Configuration({ basePath: environment.apiUrl }))
  ]
})
export class CoreModule {}

Uso en componentes (inyección del servicio generado):

constructor(private usersService: UsersService) {}
ngOnInit() {
  this.usersService.getUsers().subscribe(users => this.users = users);
}

Decisiones de arquitectura y buenas prácticas

Ejemplo rápido de interceptor para fechas:

intercept(req, next) {
  return next.handle(req).pipe(map(event => {
    if (event instanceof HttpResponse && typeof event.body === 'object') {
      traverseAndConvertDates(event.body);
    }
    return event;
  }));
}

CI/CD: proteger el contrato

Añade paso en CI para regenerar y comprobar diffs. Ejemplo GitHub Actions snippet:

- run: npm ci
- run: npm run api:generate
- run: git diff --exit-code src/app/core/api || (echo "API client changed but not committed" && exit 1)

Si hay cambios, el pipeline falla y el equipo revisa la especificación o commitea el cliente actualizado.

Errores comunes y cómo evitarlos

Conclusión

La generación de clientes OpenAPI para Angular transforma especificaciones en código útil, confiable y mantenible. No es una moda: es una práctica de ingeniería que reduce errores, acelera el desarrollo y deja claro quién es responsable del contrato. Implementa la generación con OpenAPI Generator, commitea el cliente, encapsula extensiones y protege el flujo con CI. Tu equipo y tu base de código te lo agradecerán.