OpenAPI Clean Architecture Generator

Generador de código Angular con Clean Architecture desde archivos OpenAPI/Swagger.

🚀 Instalación

Opción 1: Instalación Global

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

Opción 2: Usar directamente

npm install
npm run setup

📖 Uso

Comando básico

# Versión compilada
npm run generate -- -i swagger.yaml

# Versión desarrollo (ts-node)
npm run generate:dev -- -i swagger.yaml

# Versión link global (si hiciste npm link)
generate-clean-arch -i swagger.yaml

Opciones disponibles

npm run generate -- [opciones]

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]
  --skip-install             No instalar dependencias
  --dry-run                  Simular sin generar archivos
  -h, --help                 Mostrar ayuda

Ejemplos

# Generar desde swagger.yaml en src/app
npm run generate -- -i swagger.yaml -o ./src/app

# Usar templates personalizados
npm run generate -- -i api.yaml -t ./mis-templates

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

# Especificar todos los parámetros
npm run generate -- -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

Modificar Templates

Los templates están en la carpeta templates/. Cada archivo .mustache define cómo se genera un tipo de archivo.

Templates disponibles:

• model.mustache - DTOs
• model-entity.mustache - Entidades del modelo
• mapper.mustache - Mappers
• 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 (ej: "ORDER_TYPE")
{{description}}        - Descripción del schema
{{httpMethod}}         - Método HTTP (get, post, etc)
{{path}}               - Path del endpoint
{{nickname}}           - Nombre del método
{{allParams}}          - Todos los parámetros
{{returnType}}         - Tipo de retorno
{{vars}}               - Variables del modelo

📊 Reporte de Generación

Después de cada generación, se crea un archivo generation-report.json con estadísticas:

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

🎯 Ejemplo Completo

1. Preparar tu proyecto

# Clonar o copiar el generador
cd mi-proyecto-angular
mkdir generator
cd generator
# Copiar archivos del generador aquí

2. Copiar tu Swagger

cp ../docs/api.yaml ./swagger.yaml

3. Generar código

npm run generate -- -i swagger.yaml

4. Registrar providers en Angular

En tu app.module.ts o app.config.ts:

import { NodeRepositoryProvider } from '@/di/repositories/node.repository.provider';
import { NodeUseCasesProvider } from '@/di/use-cases/node.use-cases.provider';
// ... importar otros providers

@NgModule({
  providers: [
    // Repositories
    NodeRepositoryProvider,
    OrderTypeRepositoryProvider,
    SupplyModeRepositoryProvider,

    // Use Cases
    NodeUseCasesProvider,
    OrderTypeUseCasesProvider,
    SupplyModeUseCasesProvider
  ]
})
export class AppModule {}

5. Usar en componentes

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

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

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

🐛 Troubleshooting

Error: openapi-generator-cli no encontrado

npm install -g @openapitools/openapi-generator-cli
# o
npm run setup

Error: Archivo swagger.yaml no encontrado

Asegúrate de especificar la ruta correcta:

npm run generate -- -i ./ruta/a/tu/swagger.yaml

Los imports no se resuelven (@/ no funciona)

Configura los path aliases en tu tsconfig.json:

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

Los templates no generan el código esperado

1. Verifica que tus templates están en ./templates/
2. Revisa la sintaxis Mustache
3. Usa --dry-run para verificar sin generar archivos

📝 Notas

• El generador crea archivos .ts, no los compila
• Los providers deben registrarse manualmente en tu módulo Angular
• Asegúrate de tener configurado @mercadona/common o ajusta los imports en los templates
• El generador asume Angular 17+ con inject() function

🤝 Contribuir

Si encuentras bugs o mejoras, siéntete libre de modificar los templates y el script según tus necesidades.

📄 Licencia

MIT