285 lines
8.2 KiB
Markdown
285 lines
8.2 KiB
Markdown
# 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](https://bun.sh) >= 1.0.0
|
|
- [Java](https://www.java.com) (requerido por `openapi-generator-cli`)
|
|
|
|
## 🚀 Instalación
|
|
|
|
### Opción 1: Instalar como CLI global desde el registry
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
generate-clean-arch -i swagger.yaml
|
|
```
|
|
|
|
### Opción 2: Clonar y usar en local
|
|
|
|
```bash
|
|
git clone <repo>
|
|
cd openapi-clean-arch-generator
|
|
bun install
|
|
bun run setup # instala openapi-generator-cli globalmente
|
|
```
|
|
|
|
## 📖 Uso
|
|
|
|
### Comando básico
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](https://mustache.github.io/). 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
|
|
|
|
```mustache
|
|
{{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`:
|
|
|
|
```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
|
|
|
|
```bash
|
|
generate-clean-arch -i ./docs/api.yaml -o ./src/app
|
|
```
|
|
|
|
### 2. Registrar providers
|
|
|
|
En tu `app.config.ts` (Angular 17+ standalone):
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```bash
|
|
bun run setup
|
|
# o manualmente:
|
|
bun add -g @openapitools/openapi-generator-cli
|
|
```
|
|
|
|
### Archivo swagger.yaml no encontrado
|
|
|
|
Especifica la ruta correcta con `-i`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|