287 lines
7.7 KiB
Markdown
287 lines
7.7 KiB
Markdown
# OpenAPI Clean Architecture Generator
|
|
|
|
Generador de código Angular con Clean Architecture desde archivos OpenAPI/Swagger.
|
|
|
|
## 🚀 Instalación
|
|
|
|
### Opción 1: Instalación Global
|
|
|
|
```bash
|
|
npm install -g @openapitools/openapi-generator-cli
|
|
npm install
|
|
```
|
|
|
|
### Opción 2: Usar directamente
|
|
|
|
```bash
|
|
npm install
|
|
npm run setup
|
|
```
|
|
|
|
## 📖 Uso
|
|
|
|
### Comando básico
|
|
|
|
```bash
|
|
node generate.js -i swagger.yaml
|
|
```
|
|
|
|
### Opciones disponibles
|
|
|
|
```bash
|
|
node generate.js [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
|
|
|
|
```bash
|
|
# Generar desde swagger.yaml en src/app
|
|
node generate.js -i swagger.yaml -o ./src/app
|
|
|
|
# Usar templates personalizados
|
|
node generate.js -i api.yaml -t ./mis-templates
|
|
|
|
# Modo de prueba (no genera archivos)
|
|
node generate.js -i swagger.yaml --dry-run
|
|
|
|
# Especificar todos los parámetros
|
|
node generate.js -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
|
|
|
|
```mustache
|
|
{{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:
|
|
|
|
```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 Completo
|
|
|
|
### 1. Preparar tu proyecto
|
|
|
|
```bash
|
|
# Clonar o copiar el generador
|
|
cd mi-proyecto-angular
|
|
mkdir generator
|
|
cd generator
|
|
# Copiar archivos del generador aquí
|
|
```
|
|
|
|
### 2. Copiar tu Swagger
|
|
|
|
```bash
|
|
cp ../docs/api.yaml ./swagger.yaml
|
|
```
|
|
|
|
### 3. Generar código
|
|
|
|
```bash
|
|
node generate.js
|
|
```
|
|
|
|
### 4. Registrar providers en Angular
|
|
|
|
En tu `app.module.ts` o `app.config.ts`:
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```bash
|
|
npm install -g @openapitools/openapi-generator-cli
|
|
# o
|
|
npm run setup
|
|
```
|
|
|
|
### Error: Archivo swagger.yaml no encontrado
|
|
|
|
Asegúrate de especificar la ruta correcta:
|
|
```bash
|
|
node generate.js -i ./ruta/a/tu/swagger.yaml
|
|
```
|
|
|
|
### Los imports no se resuelven (@/ no funciona)
|
|
|
|
Configura los path aliases en tu `tsconfig.json`:
|
|
|
|
```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
|