openapi-clean-arch-gen/README.md

OpenAPI Clean Architecture Generator

Generador de código Angular con Clean Architecture desde archivos OpenAPI/Swagger. Automatiza la creación de DTOs, repositorios, mappers, casos de uso y providers de inyección de dependencias.

📦 Requisitos

• Bun >= 1.0.0
• Java (requerido por openapi-generator-cli)

🚀 Instalación

Opción 1: Instalar como CLI global desde el registry

bun add -g @blas/openapi-clean-arch-generator --registry https://git.blassanto.me/api/packages/blas/npm/

O configurando el registry en tu .npmrc / bunfig.toml:

generate-clean-arch -i swagger.yaml

Opción 2: Clonar y usar en local

git clone <repo>
cd openapi-clean-arch-generator
bun install
bun run setup   # instala openapi-generator-cli globalmente

📖 Uso

Comando básico

# Instalado globalmente
generate-clean-arch -i swagger.yaml

# Desde el repositorio (compilado)
bun run generate -- -i swagger.yaml

# Desde el repositorio (desarrollo, sin compilar)
bun run generate:dev -- -i swagger.yaml

Opciones disponibles

Opciones:
  -V, --version              Mostrar versión
  -i, --input <file>         Archivo OpenAPI/Swagger (yaml o json) [default: swagger.yaml]
  -o, --output <dir>         Directorio de salida [default: ./src/app]
  -t, --templates <dir>      Directorio de templates personalizados [default: ./templates]
  -s, --select-endpoints     Seleccionar interactivamente tags y endpoints a generar
  --skip-install             No instalar dependencias
  --dry-run                  Simular sin generar archivos
  -h, --help                 Mostrar ayuda

Ejemplos

# Generar desde swagger.yaml en src/app
generate-clean-arch -i swagger.yaml -o ./src/app

# Seleccionar tags/endpoints de forma interactiva
generate-clean-arch -i api.yaml -s

# Usar templates personalizados
generate-clean-arch -i api.yaml -t ./mis-templates

# Modo de prueba (no genera archivos)
generate-clean-arch -i swagger.yaml --dry-run

# Especificar todos los parámetros
generate-clean-arch -i ./docs/api.yaml -o ./frontend/src/app -t ./custom-templates

📁 Estructura Generada

El generador crea la siguiente estructura siguiendo Clean Architecture:

src/app/
├── data/                          # Capa de datos
│   ├── dtos/                      # Data Transfer Objects
│   │   ├── node/
│   │   │   └── node.dto.ts
│   │   ├── order-type/
│   │   │   └── order-type.dto.ts
│   │   └── supply-mode/
│   │       └── supply-mode.dto.ts
│   ├── repositories/              # Implementaciones de repositorios
│   │   ├── node.repository.impl.ts
│   │   ├── order-type.repository.impl.ts
│   │   └── supply-mode.repository.impl.ts
│   └── mappers/                   # Transformadores DTO → Entidad
│       ├── node.mapper.ts
│       ├── order-type.mapper.ts
│       └── supply-mode.mapper.ts
├── domain/                        # Capa de dominio
│   ├── repositories/              # Contratos de repositorios
│   │   ├── node.repository.contract.ts
│   │   ├── order-type.repository.contract.ts
│   │   └── supply-mode.repository.contract.ts
│   └── use-cases/                 # Casos de uso
│       ├── node/
│       │   ├── node.use-cases.contract.ts
│       │   └── node.use-cases.impl.ts
│       ├── order-type/
│       │   ├── order-type.use-cases.contract.ts
│       │   └── order-type.use-cases.impl.ts
│       └── supply-mode/
│           ├── supply-mode.use-cases.contract.ts
│           └── supply-mode.use-cases.impl.ts
├── di/                            # Inyección de dependencias
│   ├── repositories/              # Providers de repositorios
│   │   ├── node.repository.provider.ts
│   │   ├── order-type.repository.provider.ts
│   │   └── supply-mode.repository.provider.ts
│   └── use-cases/                 # Providers de use cases
│       ├── node.use-cases.provider.ts
│       ├── order-type.use-cases.provider.ts
│       └── supply-mode.use-cases.provider.ts
└── entities/                      # Entidades de dominio
    └── models/
        ├── node.model.ts
        ├── order-type.model.ts
        └── supply-mode.model.ts

🔧 Personalización de Templates

Los templates están en templates/ y usan sintaxis Mustache. Puedes sobreescribirlos pasando tu propio directorio con -t.

Template	Genera
model.mustache	DTOs
model-entity.mustache	Entidades de dominio
mapper.mustache	Mappers DTO → Entidad
api.repository.contract.mustache	Contratos de repositorio
api.repository.impl.mustache	Implementaciones de repositorio
api.use-cases.contract.mustache	Contratos de use cases
api.use-cases.impl.mustache	Implementaciones de use cases
repository.provider.mustache	Providers de repositorio
use-cases.provider.mustache	Providers de use cases

Variables Mustache disponibles

{{classname}}          - Nombre de la clase (ej: "OrderType")
{{classVarName}}       - Nombre en camelCase (ej: "orderType")
{{classFilename}}      - Nombre del archivo (ej: "order-type")
{{constantName}}       - Constante en UPPER_SNAKE_CASE (ej: "ORDER_TYPE")
{{description}}        - Descripción del schema
{{httpMethod}}         - Método HTTP (get, post, put, delete…)
{{path}}               - Path del endpoint
{{nickname}}           - Nombre del método
{{allParams}}          - Todos los parámetros del endpoint
{{returnType}}         - Tipo de retorno
{{vars}}               - Variables del modelo

📊 Reporte de Generación

Tras cada ejecución se crea generation-report.json:

{
  "timestamp": "2025-01-15T10:30:00.000Z",
  "tags": 3,
  "endpoints": 8,
  "outputDirectory": "./src/app",
  "structure": {
    "dtos": 15,
    "repositories": 9,
    "mappers": 3,
    "useCases": 6
  }
}

🎯 Ejemplo de integración en Angular

1. Generar código

generate-clean-arch -i ./docs/api.yaml -o ./src/app

2. Registrar providers

En tu app.config.ts (Angular 17+ standalone):

import { ApplicationConfig } from '@angular/core';
import { NodeRepositoryProvider } from './di/repositories/node.repository.provider';
import { NodeUseCasesProvider } from './di/use-cases/node.use-cases.provider';

export const appConfig: ApplicationConfig = {
  providers: [
    NodeRepositoryProvider,
    NodeUseCasesProvider,
    // ... resto de providers generados
  ]
};

3. Usar en componentes

import { Component, inject } from '@angular/core';
import { NODE_USE_CASES } from './domain/use-cases/node/node.use-cases.contract';

@Component({
  selector: 'app-nodes',
  template: `...`
})
export class NodesComponent {
  readonly #nodeUseCases = inject(NODE_USE_CASES);

  loadNodes(): void {
    this.#nodeUseCases.getNodes().subscribe((nodes) => {
      console.log(nodes);
    });
  }
}

🐛 Troubleshooting

openapi-generator-cli no encontrado

bun run setup
# o manualmente:
bun add -g @openapitools/openapi-generator-cli

Archivo swagger.yaml no encontrado

Especifica la ruta correcta con -i:

generate-clean-arch -i ./ruta/a/tu/api.yaml

Los path aliases @/ no se resuelven

Configura los aliases en el tsconfig.json de tu proyecto Angular:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["src/app/*"]
    }
  }
}

Los templates no generan el código esperado

1. Verifica que tus templates están en ./templates/ o pasa la ruta con -t
2. Revisa la sintaxis Mustache
3. Usa --dry-run para simular sin escribir archivos

📝 Notas

• El generador produce archivos .ts listos para usar, no los compila
• Los providers deben registrarse manualmente en tu módulo o config de Angular
• Requiere Angular 17+ (usa la función inject())
• Compatible con proyectos standalone y basados en módulos

🤝 Contribuir

Si encuentras bugs o mejoras, abre un issue o PR en el repositorio.

📄 Licencia

MIT