diff --git a/README.md b/README.md index b10d3ea..5946b7d 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,33 @@ # OpenAPI Clean Architecture Generator -Generador de código Angular con Clean Architecture desde archivos OpenAPI/Swagger. +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: Instalación Global +### Opción 1: Instalar como CLI global desde el registry ```bash -npm install -g @openapitools/openapi-generator-cli -npm install +bun add -g @blas/openapi-clean-arch-generator --registry https://git.blassanto.me/api/packages/blas/npm/ ``` -### Opción 2: Usar directamente +O configurando el registry en tu `.npmrc` / `bunfig.toml`: ```bash -npm install -npm run setup +generate-clean-arch -i swagger.yaml +``` + +### Opción 2: Clonar y usar en local + +```bash +git clone +cd openapi-clean-arch-generator +bun install +bun run setup # instala openapi-generator-cli globalmente ``` ## 📖 Uso @@ -23,26 +35,25 @@ npm run setup ### Comando básico ```bash -# 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) +# 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 -```bash -npm run generate -- [opciones] - +``` Opciones: -V, --version Mostrar versión -i, --input Archivo OpenAPI/Swagger (yaml o json) [default: swagger.yaml] -o, --output Directorio de salida [default: ./src/app] -t, --templates 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 @@ -52,16 +63,19 @@ Opciones: ```bash # Generar desde swagger.yaml en src/app -npm run generate -- -i swagger.yaml -o ./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 -npm run generate -- -i api.yaml -t ./mis-templates +generate-clean-arch -i api.yaml -t ./mis-templates # Modo de prueba (no genera archivos) -npm run generate -- -i swagger.yaml --dry-run +generate-clean-arch -i swagger.yaml --dry-run # Especificar todos los parámetros -npm run generate -- -i ./docs/api.yaml -o ./frontend/src/app -t ./custom-templates +generate-clean-arch -i ./docs/api.yaml -o ./frontend/src/app -t ./custom-templates ``` ## 📁 Estructura Generada @@ -117,43 +131,41 @@ src/app/ └── supply-mode.model.ts ``` -## 🔧 Personalización +## 🔧 Personalización de Templates -### Modificar Templates +Los templates están en `templates/` y usan sintaxis [Mustache](https://mustache.github.io/). Puedes sobreescribirlos pasando tu propio directorio con `-t`. -Los templates están en la carpeta `templates/`. Cada archivo `.mustache` define cómo se genera un tipo de archivo. +| 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 | -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 +### 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") +{{constantName}} - Constante en UPPER_SNAKE_CASE (ej: "ORDER_TYPE") {{description}} - Descripción del schema -{{httpMethod}} - Método HTTP (get, post, etc) +{{httpMethod}} - Método HTTP (get, post, put, delete…) {{path}} - Path del endpoint {{nickname}} - Nombre del método -{{allParams}} - Todos los parámetros +{{allParams}} - Todos los parámetros del endpoint {{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: +Tras cada ejecución se crea `generation-report.json`: ```json { @@ -170,70 +182,47 @@ Después de cada generación, se crea un archivo `generation-report.json` con es } ``` -## 🎯 Ejemplo Completo +## 🎯 Ejemplo de integración en Angular -### 1. Preparar tu proyecto +### 1. Generar código ```bash -# Clonar o copiar el generador -cd mi-proyecto-angular -mkdir generator -cd generator -# Copiar archivos del generador aquí +generate-clean-arch -i ./docs/api.yaml -o ./src/app ``` -### 2. Copiar tu Swagger +### 2. Registrar providers -```bash -cp ../docs/api.yaml ./swagger.yaml -``` - -### 3. Generar código - -```bash -npm run generate -- -i swagger.yaml -``` - -### 4. Registrar providers en Angular - -En tu `app.module.ts` o `app.config.ts`: +En tu `app.config.ts` (Angular 17+ standalone): ```typescript -import { NodeRepositoryProvider } from '@/di/repositories/node.repository.provider'; -import { NodeUseCasesProvider } from '@/di/use-cases/node.use-cases.provider'; -// ... importar otros providers +import { ApplicationConfig } from '@angular/core'; +import { NodeRepositoryProvider } from './di/repositories/node.repository.provider'; +import { NodeUseCasesProvider } from './di/use-cases/node.use-cases.provider'; -@NgModule({ +export const appConfig: ApplicationConfig = { providers: [ - // Repositories NodeRepositoryProvider, - OrderTypeRepositoryProvider, - SupplyModeRepositoryProvider, - - // Use Cases NodeUseCasesProvider, - OrderTypeUseCasesProvider, - SupplyModeUseCasesProvider + // ... resto de providers generados ] -}) -export class AppModule {} +}; ``` -### 5. Usar en componentes +### 3. Usar en componentes ```typescript import { Component, inject } from '@angular/core'; -import { NODE_USE_CASES, NodeUseCases } from '@/domain/use-cases/node/node.use-cases.contract'; +import { NODE_USE_CASES } from './domain/use-cases/node/node.use-cases.contract'; @Component({ selector: 'app-nodes', template: `...` }) export class NodesComponent { - #nodeUseCases = inject(NODE_USE_CASES); + readonly #nodeUseCases = inject(NODE_USE_CASES); - loadNodes() { - this.#nodeUseCases.getNodes('TI').subscribe((nodes) => { + loadNodes(): void { + this.#nodeUseCases.getNodes().subscribe((nodes) => { console.log(nodes); }); } @@ -242,32 +231,31 @@ export class NodesComponent { ## 🐛 Troubleshooting -### Error: openapi-generator-cli no encontrado +### `openapi-generator-cli` no encontrado ```bash -npm install -g @openapitools/openapi-generator-cli -# o -npm run setup +bun run setup +# o manualmente: +bun add -g @openapitools/openapi-generator-cli ``` -### Error: Archivo swagger.yaml no encontrado +### Archivo swagger.yaml no encontrado -Asegúrate de especificar la ruta correcta: +Especifica la ruta correcta con `-i`: ```bash -npm run generate -- -i ./ruta/a/tu/swagger.yaml +generate-clean-arch -i ./ruta/a/tu/api.yaml ``` -### Los imports no se resuelven (@/ no funciona) +### Los path aliases `@/` no se resuelven -Configura los path aliases en tu `tsconfig.json`: +Configura los aliases en el `tsconfig.json` de tu proyecto Angular: ```json { "compilerOptions": { "paths": { - "@/*": ["src/app/*"], - "@environment": ["src/environments/environment"] + "@/*": ["src/app/*"] } } } @@ -275,21 +263,22 @@ Configura los path aliases en tu `tsconfig.json`: ### Los templates no generan el código esperado -1. Verifica que tus templates están en `./templates/` +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 verificar sin generar archivos +3. Usa `--dry-run` para simular sin escribir 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 +- 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, siéntete libre de modificar los templates y el script según tus necesidades. +Si encuentras bugs o mejoras, abre un issue o PR en el repositorio. ## 📄 Licencia MIT +