blas/openapi-clean-arch-gen
1
0
Fork 0
Code Issues 3 Pull Requests 1 Actions Packages Projects 1 Releases 6 Wiki Activity

chore: migrate from node to bun

Browse Source
This commit is contained in:
blas
2026-03-25 10:25:23 +01:00
parent 04d2299a4c
commit 21b0333788
1 changed files with 87 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
README.md
View File

@@ -1,21 +1,33 @@
# OpenAPI Clean Architecture Generator # 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 ## 🚀 Instalación
### Opción 1: Instalación Global ### Opción 1: Instalar como CLI global desde el registry
```bash ```bash
npm install -g @openapitools/openapi-generator-cli bun add -g @blas/openapi-clean-arch-generator --registry https://git.blassanto.me/api/packages/blas/npm/
npm install
``` ```
### Opción 2: Usar directamente O configurando el registry en tu `.npmrc` / `bunfig.toml`:
```bash ```bash
npm install generate-clean-arch -i swagger.yaml
npm run setup ```
### 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 ## 📖 Uso
@@ -23,26 +35,25 @@ npm run setup
### Comando básico ### Comando básico
```bash ```bash
# Versión compilada # Instalado globalmente
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 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 disponibles
```bash ```
npm run generate -- [opciones]
Opciones: Opciones:
-V, --version Mostrar versión -V, --version Mostrar versión
-i, --input <file> Archivo OpenAPI/Swagger (yaml o json) [default: swagger.yaml] -i, --input <file> Archivo OpenAPI/Swagger (yaml o json) [default: swagger.yaml]
-o, --output <dir> Directorio de salida [default: ./src/app] -o, --output <dir> Directorio de salida [default: ./src/app]
-t, --templates <dir> Directorio de templates personalizados [default: ./templates] -t, --templates <dir> Directorio de templates personalizados [default: ./templates]
-s, --select-endpoints Seleccionar interactivamente tags y endpoints a generar
--skip-install No instalar dependencias --skip-install No instalar dependencias
--dry-run Simular sin generar archivos --dry-run Simular sin generar archivos
-h, --help Mostrar ayuda -h, --help Mostrar ayuda
@@ -52,16 +63,19 @@ Opciones:
```bash ```bash
# Generar desde swagger.yaml en src/app # 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 # 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) # 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 # 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 ## 📁 Estructura Generada
@@ -117,43 +131,41 @@ src/app/
└── supply-mode.model.ts └── 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: ### Variables Mustache 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 ```mustache
{{classname}} - Nombre de la clase (ej: "OrderType") {{classname}} - Nombre de la clase (ej: "OrderType")
{{classVarName}} - Nombre en camelCase (ej: "orderType") {{classVarName}} - Nombre en camelCase (ej: "orderType")
{{classFilename}} - Nombre del archivo (ej: "order-type") {{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 {{description}} - Descripción del schema
{{httpMethod}} - Método HTTP (get, post, etc) {{httpMethod}} - Método HTTP (get, post, put, delete…)
{{path}} - Path del endpoint {{path}} - Path del endpoint
{{nickname}} - Nombre del método {{nickname}} - Nombre del método
{{allParams}} - Todos los parámetros {{allParams}} - Todos los parámetros del endpoint
{{returnType}} - Tipo de retorno {{returnType}} - Tipo de retorno
{{vars}} - Variables del modelo {{vars}} - Variables del modelo
``` ```
## 📊 Reporte de Generación ## 📊 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 ```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 ```bash
# Clonar o copiar el generador generate-clean-arch -i ./docs/api.yaml -o ./src/app
cd mi-proyecto-angular
mkdir generator
cd generator
# Copiar archivos del generador aquí
``` ```
### 2. Copiar tu Swagger ### 2. Registrar providers
```bash En tu `app.config.ts` (Angular 17+ standalone):
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`:
```typescript ```typescript
import { NodeRepositoryProvider } from '@/di/repositories/node.repository.provider'; import { ApplicationConfig } from '@angular/core';
import { NodeUseCasesProvider } from '@/di/use-cases/node.use-cases.provider'; import { NodeRepositoryProvider } from './di/repositories/node.repository.provider';
// ... importar otros providers import { NodeUseCasesProvider } from './di/use-cases/node.use-cases.provider';
@NgModule({ export const appConfig: ApplicationConfig = {
providers: [ providers: [
// Repositories
NodeRepositoryProvider, NodeRepositoryProvider,
OrderTypeRepositoryProvider,
SupplyModeRepositoryProvider,
// Use Cases
NodeUseCasesProvider, NodeUseCasesProvider,
OrderTypeUseCasesProvider, // ... resto de providers generados
SupplyModeUseCasesProvider
] ]
}) };
export class AppModule {}
``` ```
### 5. Usar en componentes ### 3. Usar en componentes
```typescript ```typescript
import { Component, inject } from '@angular/core'; 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({ @Component({
selector: 'app-nodes', selector: 'app-nodes',
template: `...` template: `...`
}) })
export class NodesComponent { export class NodesComponent {
#nodeUseCases = inject(NODE_USE_CASES); readonly #nodeUseCases = inject(NODE_USE_CASES);
loadNodes() { loadNodes(): void {
this.#nodeUseCases.getNodes('TI').subscribe((nodes) => { this.#nodeUseCases.getNodes().subscribe((nodes) => {
console.log(nodes); console.log(nodes);
}); });
} }
@@ -242,32 +231,31 @@ export class NodesComponent {
## 🐛 Troubleshooting ## 🐛 Troubleshooting
### Error: openapi-generator-cli no encontrado ### `openapi-generator-cli` no encontrado
```bash ```bash
npm install -g @openapitools/openapi-generator-cli bun run setup
# o # o manualmente:
npm run setup 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 ```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 ```json
{ {
"compilerOptions": { "compilerOptions": {
"paths": { "paths": {
"@/*": ["src/app/*"], "@/*": ["src/app/*"]
"@environment": ["src/environments/environment"]
} }
} }
} }
@@ -275,21 +263,22 @@ Configura los path aliases en tu `tsconfig.json`:
### Los templates no generan el código esperado ### 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 2. Revisa la sintaxis Mustache
3. Usa `--dry-run` para verificar sin generar archivos 3. Usa `--dry-run` para simular sin escribir archivos
## 📝 Notas ## 📝 Notas
- El generador crea archivos `.ts`, no los compila - El generador produce archivos `.ts` listos para usar, no los compila
- Los providers deben registrarse manualmente en tu módulo Angular - Los providers deben registrarse manualmente en tu módulo o config de Angular
- Asegúrate de tener configurado `@mercadona/common` o ajusta los imports en los templates - Requiere Angular 17+ (usa la función `inject()`)
- El generador asume Angular 17+ con inject() function - Compatible con proyectos standalone y basados en módulos
## 🤝 Contribuir ## 🤝 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 ## 📄 Licencia
MIT MIT