@devlearning/swagger-generator 1.1.8 → 1.1.10

package/README-OLD.md

@@ -0,0 +1,210 @@
+# Swagger Generator for Angular, Next.js and Flutter
+
+This tool automates the generation of API clients for Angular, Next.js and Flutter using a Swagger (OpenAPI) specification. It creates TypeScript models and service classes, making API integration seamless and type-safe.
+
+## Features
+
+- 🚀 **Automatic Model Generation** – Converts Swagger schemas into TypeScript interfaces or classes.
+- 🔥 **API Client Generation** – Creates service methods for making API calls with authentication, headers, and request parameters.
+- 🎯 **Framework-Specific Output**:
+  - **Angular** – Generates injectable services using `HttpClient`.
+  - **Next.js** – Provides fetch-based or Axios-based API functions, optimized for both server-side and client-side usage.
+  - **Flutter** – Provides Flutter with Dio API functions, optimized for both server-side and client-side usage.
+- ✅ **Strong Typing** – Ensures type safety for API requests and responses.
+- ⚡ **Customization** – Configurable options for method naming, error handling, and request structure.
+- 🔄 **Auto-Sync with Backend** – Keeps API clients up-to-date with backend changes.
+
+## Installation
+
+```sh
+npm i @devlearning/swagger-generator --save-dev
+```
+
+
+add npm script:
+
+  "swgen": "swgen http://localhost:7550/swagger/ApiGateway/swagger.json src/app/core/autogenerated angular moment"
+
+params:
+  - url of swagger.json: not https
+  - output path for autogenerated files: src/app/core/autogenerated
+  - target framework/library: angular/next
+  - type of date management:
+    - angular only support momentjs, sorry :(
+    - nextjs only support date-fns
+    - dart native date management
+
+create output path like this: src/app/core/autogenerated
+
+## Angular configuration
+
+create ApiService like this
+```ts
+import { HttpClient, HttpErrorResponse } from '@angular/common/http';
+import { Injectable } from '@angular/core';
+import { ApiAutogeneratedService } from '../autogenerated/api.autogenerated';
+import { environment } from 'src/environments/environment';
+import { ResponseError } from '../models/response-error';
+import { throwError } from 'rxjs';
+import * as moment from 'moment-timezone';
+
+@Injectable({
+  providedIn: 'root',
+})
+export class ApiService extends ApiAutogeneratedService {
+
+  private _dateTimeFormat = /^((19|20)[0-9][0-9])[-](0[1-9]|1[012])[-](0[1-9]|[12][0-9]|3[01])[T]([01]?[0-9]|[2][0-3])[:]([0-5][0-9])[:]([0-5][0-9])[.]([0-9][0-9][0-9])([+|-]([01][0-9]|[2][0-3])[:]([0-5][0-9])){0,1}$/;
+  private _timeFormat = /^([01]?[0-9]|[2][0-3])[:]([0-5][0-9])[:]([0-5][0-9])[.]([0-9][0-9][0-9])$/;
+  private _ianaName: string = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  private _dateTimeFormatString = "YYYY-MM-DDTHH:mm:ss.SSSZ";
+  private _timeFormatString = "HH:mm:ss.SSS";
+
+  public get ianaName() { return this._ianaName; }
+
+  constructor(
+    public override _http: HttpClient,
+  ) {
+    super(_http, environment.BASE_URL);
+  }
+
+  protected override _momentToString(moment: moment.Moment) {
+    return (<moment.Moment>moment).format(this._dateTimeFormatString);
+  }
+
+  protected override _handleRequest<T>(request: T) {
+    if (request === null || request === undefined) {
+      return request;
+    }
+    if (typeof request !== 'object') {
+      return request;
+    }
+
+    var clonedRequest = { ...request };
+
+    for (const key of Object.keys(clonedRequest)) {
+      const value = (<any>clonedRequest)[key];
+      if (moment.isMoment(value)) {
+        (<any>clonedRequest)[key] = this._momentToString(value);
+      } else if (typeof value === 'object') {
+        this._handleRequest(value);
+      }
+    }
+
+    return clonedRequest;
+  }
+
+  protected override _handleMultipart<T>(request: T): FormData {
+    const formData = new FormData();
+    if (request === null || request === undefined) {
+      return formData;
+    }
+
+    for (const key of Object.keys(request)) {
+      const value = (<any>request)[key];
+      if (value instanceof File) {
+        formData.append(key, value, value.name);
+      } else {
+        formData.append(key, value.toString());
+      }
+    }
+
+    return formData;
+  }
+
+  public override _handleResponse<T>(response: T) {
+    if (response === null || response === undefined) {
+      return response;
+    }
+    if (typeof response !== 'object') {
+      return response;
+    }
+
+    for (const key of Object.keys(response)) {
+      const value = (<any>response)[key];
+      if (this._isDateString(value)) {
+        (<any>response)[key] = moment.tz(value, this._dateTimeFormatString, this._ianaName);
+      } else if (this._isTimeString(value)) {
+        (<any>response)[key] = moment.tz(value, this._timeFormatString, this._ianaName);
+      } else if (typeof value === 'object') {
+        this._handleResponse(value);
+      }
+    }
+
+    return response;
+  }
+
+  protected override _handleError(error: any, obs: any) {
+    let responseError = new ResponseError();
+    if (error.error instanceof Error) {
+      console.error('Api - an error occurred:', error.error.message);
+      responseError.message = error.error.message;
+    } else if (error instanceof HttpErrorResponse) {
+      responseError = ResponseError.CreateFromHttpErrorResponse(error);
+    }
+
+    console.error(`Api - error code ${error.status} message ${responseError.message} ${responseError.stacktrace}`);
+    
+    return throwError(() => responseError);
+  }
+
+  private _isDateString(value: string) {
+    if (value === null || value === undefined) {
+      return false;
+    }
+    if (typeof value === 'string') {
+      return this._dateTimeFormat.test(value);
+    }
+    return false;
+  }
+
+  private _isTimeString(value: string) {
+    if (value === null || value === undefined) {
+      return false;
+    }
+    if (typeof value === 'string') {
+      return this._timeFormat.test(value);
+    }
+    return false;
+  }
+}
+```
+
+
+```ts
+import { HttpErrorResponse } from '@angular/common/http';
+
+export class ResponseError {
+  public url: string | null;
+  public status: number | null;
+  public message: string | null;
+  public stacktrace: string | null;
+
+  constructor() {
+    this.url = null;
+    this.status = null;
+    this.message = null;
+    this.stacktrace = null;
+  }
+
+  static CreateFromHttpErrorResponse(httpErrorResponse: HttpErrorResponse) {
+    let responseError = new ResponseError();
+
+    if (httpErrorResponse.error != null && !(httpErrorResponse.error instanceof ProgressEvent)) {
+      if (httpErrorResponse.error.hasOwnProperty('message')) {
+        responseError.message = httpErrorResponse.error.message;
+      }
+
+      if (httpErrorResponse.error.hasOwnProperty('stacktrace')) {
+        responseError.stacktrace = httpErrorResponse.error.stacktrace;
+      }
+    } else {
+      responseError.message = httpErrorResponse.message;
+    }
+
+    responseError.status = httpErrorResponse.status;
+    responseError.url = httpErrorResponse.url;
+
+    return responseError;
+  }
+}
+```

package/README.md

@@ -1,210 +1,223 @@
-# Swagger Generator for Angular, Next.js and Flutter
+# Swagger API Generator
 
-This tool automates the generation of API clients for Angular, Next.js and Flutter using a Swagger (OpenAPI) specification. It creates TypeScript models and service classes, making API integration seamless and type-safe.
+Generatore automatico di client API e modelli per **Angular**, **Next.js** e **Flutter/Dart** da specifiche Swagger/OpenAPI.
 
-## Features
+[![npm version](https://img.shields.io/npm/v/@devlearning/swagger-generator.svg)](https://www.npmjs.com/package/@devlearning/swagger-generator)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
-- 🚀 **Automatic Model Generation** – Converts Swagger schemas into TypeScript interfaces or classes.
-- 🔥 **API Client Generation** – Creates service methods for making API calls with authentication, headers, and request parameters.
-- 🎯 **Framework-Specific Output**:
-  - **Angular** – Generates injectable services using `HttpClient`.
-  - **Next.js** – Provides fetch-based or Axios-based API functions, optimized for both server-side and client-side usage.
-  - **Flutter** – Provides Flutter with Dio API functions, optimized for both server-side and client-side usage.
-- ✅ **Strong Typing** – Ensures type safety for API requests and responses.
-- ⚡ **Customization** – Configurable options for method naming, error handling, and request structure.
-- 🔄 **Auto-Sync with Backend** – Keeps API clients up-to-date with backend changes.
+## 🎯 Caratteristiche
 
-## Installation
+- ✅ **Generazione automatica** di modelli e API da Swagger JSON
+- 🎨 **Multi-framework**: Angular, Next.js, Flutter/Dart
+- 🔒 **Type-safe**: Tipizzazione forte per TypeScript e Dart
+- 📦 **Zero dipendenze** nei file generati (configurabile)
+- 🚀 **CLI semplice** da usare
+- 🔄 **Validazione** del documento Swagger prima della generazione
+- 📝 **Logging strutturato** per debugging
 
-```sh
-npm i @devlearning/swagger-generator --save-dev
+## 📦 Installazione
+
+```bash
+npm install @devlearning/swagger-generator --save-dev
+```
+
+## 🚀 Utilizzo
+
+### Da linea di comando
+
+```bash
+npx swgen --url <swagger-url> --output <output-dir> --target <angular|next|flutter> [opzioni]
+```
+
+### Esempi
+
+#### Angular
+```bash
+npx swgen \
+  --url http://localhost:5000/swagger/v1/swagger.json \
+  --output src/app/core/autogen \
+  --target angular \
+  --dateTimeLibrary moment
 ```
 
+#### Next.js
+```bash
+npx swgen \
+  --url https://api.example.com/swagger.json \
+  --output src/lib/api \
+  --target next \
+  --dateTimeLibrary date-fns
+```
 
-add npm script:
+#### Flutter/Dart
+```bash
+npx swgen \
+  --url http://localhost:5000/swagger/v1/swagger.json \
+  --output lib/core/api \
+  --target flutter \
+  --package my_app_name
+```
 
-  "swgen": "swgen http://localhost:7550/swagger/ApiGateway/swagger.json src/app/core/autogenerated angular moment"
+### Opzioni
 
-params:
-  - url of swagger.json: not https
-  - output path for autogenerated files: src/app/core/autogenerated
-  - target framework/library: angular/next
-  - type of date management:
-    - angular only support momentjs, sorry :(
-    - nextjs only support date-fns
-    - dart native date management
+| Opzione | Alias | Descrizione | Obbligatorio | Default |
+|---------|-------|-------------|--------------|---------|
+| `--url` | `-u` | URL del file swagger.json | ✅ | - |
+| `--output` | `-o` | Directory di output | ✅ | - |
+| `--target` | `-t` | Framework target (`angular`, `next`, `flutter`) | ✅ | - |
+| `--dateTimeLibrary` | `-d` | Libreria date (`moment`, `date-fns`) | ❌ | `date-fns` |
+| `--package` | `-p` | Nome package (solo Dart/Flutter) | ❌ | - |
 
-create output path like this: src/app/core/autogenerated
+## 📁 Struttura File Generati
 
-## Angular configuration
+### Angular
+```
+output/
+├── models/
+│   ├── user.model.ts
+│   ├── product.model.ts
+│   └── ...
+└── api/
+    ├── user.api.ts
+    ├── product.api.ts
+    └── ...
+```
 
-create ApiService like this
-```ts
-import { HttpClient, HttpErrorResponse } from '@angular/common/http';
+### Next.js
+```
+output/
+├── models/
+│   ├── user.ts
+│   ├── product.ts
+│   └── ...
+└── api/
+    ├── user-api.ts
+    ├── product-api.ts
+    └── ...
+```
+
+### Flutter/Dart
+```
+lib/output/
+├── user/
+│   ├── models/
+│   │   └── user.dart
+│   └── api/
+│       └── user_api.dart
+└── product/
+    ├── models/
+    │   └── product.dart
+    └── api/
+        └── product_api.dart
+```
+
+## 🔧 Integrazione nel Progetto
+
+### Angular
+
+1. Crea un service wrapper:
+
+```typescript
 import { Injectable } from '@angular/core';
-import { ApiAutogeneratedService } from '../autogenerated/api.autogenerated';
-import { environment } from 'src/environments/environment';
-import { ResponseError } from '../models/response-error';
-import { throwError } from 'rxjs';
-import * as moment from 'moment-timezone';
-
-@Injectable({
-  providedIn: 'root',
-})
-export class ApiService extends ApiAutogeneratedService {
-
-  private _dateTimeFormat = /^((19|20)[0-9][0-9])[-](0[1-9]|1[012])[-](0[1-9]|[12][0-9]|3[01])[T]([01]?[0-9]|[2][0-3])[:]([0-5][0-9])[:]([0-5][0-9])[.]([0-9][0-9][0-9])([+|-]([01][0-9]|[2][0-3])[:]([0-5][0-9])){0,1}$/;
-  private _timeFormat = /^([01]?[0-9]|[2][0-3])[:]([0-5][0-9])[:]([0-5][0-9])[.]([0-9][0-9][0-9])$/;
-  private _ianaName: string = Intl.DateTimeFormat().resolvedOptions().timeZone;
-  private _dateTimeFormatString = "YYYY-MM-DDTHH:mm:ss.SSSZ";
-  private _timeFormatString = "HH:mm:ss.SSS";
-
-  public get ianaName() { return this._ianaName; }
-
-  constructor(
-    public override _http: HttpClient,
-  ) {
-    super(_http, environment.BASE_URL);
-  }
-
-  protected override _momentToString(moment: moment.Moment) {
-    return (<moment.Moment>moment).format(this._dateTimeFormatString);
-  }
-
-  protected override _handleRequest<T>(request: T) {
-    if (request === null || request === undefined) {
-      return request;
-    }
-    if (typeof request !== 'object') {
-      return request;
-    }
-
-    var clonedRequest = { ...request };
-
-    for (const key of Object.keys(clonedRequest)) {
-      const value = (<any>clonedRequest)[key];
-      if (moment.isMoment(value)) {
-        (<any>clonedRequest)[key] = this._momentToString(value);
-      } else if (typeof value === 'object') {
-        this._handleRequest(value);
-      }
-    }
-
-    return clonedRequest;
-  }
-
-  protected override _handleMultipart<T>(request: T): FormData {
-    const formData = new FormData();
-    if (request === null || request === undefined) {
-      return formData;
-    }
-
-    for (const key of Object.keys(request)) {
-      const value = (<any>request)[key];
-      if (value instanceof File) {
-        formData.append(key, value, value.name);
-      } else {
-        formData.append(key, value.toString());
-      }
-    }
-
-    return formData;
-  }
-
-  public override _handleResponse<T>(response: T) {
-    if (response === null || response === undefined) {
-      return response;
-    }
-    if (typeof response !== 'object') {
-      return response;
-    }
-
-    for (const key of Object.keys(response)) {
-      const value = (<any>response)[key];
-      if (this._isDateString(value)) {
-        (<any>response)[key] = moment.tz(value, this._dateTimeFormatString, this._ianaName);
-      } else if (this._isTimeString(value)) {
-        (<any>response)[key] = moment.tz(value, this._timeFormatString, this._ianaName);
-      } else if (typeof value === 'object') {
-        this._handleResponse(value);
-      }
-    }
-
-    return response;
-  }
-
-  protected override _handleError(error: any, obs: any) {
-    let responseError = new ResponseError();
-    if (error.error instanceof Error) {
-      console.error('Api - an error occurred:', error.error.message);
-      responseError.message = error.error.message;
-    } else if (error instanceof HttpErrorResponse) {
-      responseError = ResponseError.CreateFromHttpErrorResponse(error);
-    }
-
-    console.error(`Api - error code ${error.status} message ${responseError.message} ${responseError.stacktrace}`);
-    
-    return throwError(() => responseError);
-  }
-
-  private _isDateString(value: string) {
-    if (value === null || value === undefined) {
-      return false;
-    }
-    if (typeof value === 'string') {
-      return this._dateTimeFormat.test(value);
-    }
-    return false;
-  }
-
-  private _isTimeString(value: string) {
-    if (value === null || value === undefined) {
-      return false;
-    }
-    if (typeof value === 'string') {
-      return this._timeFormat.test(value);
-    }
-    return false;
-  }
+import { HttpClient } from '@angular/common/http';
+import { environment } from '@env/environment';
+
+@Injectable({ providedIn: 'root' })
+export class ApiService {
+  constructor(private http: HttpClient) {}
+  
+  // I tuoi metodi personalizzati qui
 }
 ```
 
+2. Usa i modelli generati:
 
-```ts
-import { HttpErrorResponse } from '@angular/common/http';
+```typescript
+import { User } from './autogen/models/user.model';
+import { UserApi } from './autogen/api/user.api';
+```
 
-export class ResponseError {
-  public url: string | null;
-  public status: number | null;
-  public message: string | null;
-  public stacktrace: string | null;
+### Next.js
 
-  constructor() {
-    this.url = null;
-    this.status = null;
-    this.message = null;
-    this.stacktrace = null;
-  }
+```typescript
+import { getUsers } from '@/lib/api/user-api';
+import { User } from '@/lib/api/models/user';
 
-  static CreateFromHttpErrorResponse(httpErrorResponse: HttpErrorResponse) {
-    let responseError = new ResponseError();
+export async function UsersPage() {
+  const users = await getUsers();
+  // ...
+}
+```
 
-    if (httpErrorResponse.error != null && !(httpErrorResponse.error instanceof ProgressEvent)) {
-      if (httpErrorResponse.error.hasOwnProperty('message')) {
-        responseError.message = httpErrorResponse.error.message;
-      }
+### Flutter/Dart
 
-      if (httpErrorResponse.error.hasOwnProperty('stacktrace')) {
-        responseError.stacktrace = httpErrorResponse.error.stacktrace;
-      }
-    } else {
-      responseError.message = httpErrorResponse.message;
-    }
+```dart
+import 'package:my_app/core/api/user/api/user_api.dart';
+import 'package:my_app/core/api/user/models/user.dart';
 
-    responseError.status = httpErrorResponse.status;
-    responseError.url = httpErrorResponse.url;
+final userApi = UserApi();
+final users = await userApi.getUsers();
+```
 
-    return responseError;
-  }
-}
-```
+## 🐛 Risoluzione Problemi
+
+### Errore: "Swagger validation failed"
+Il documento Swagger non è valido. Verifica:
+- Presenza di `openApi` version
+- Presenza di `paths` object
+- Struttura corretta delle definizioni
+
+### Errore: "Cannot parse null data"
+L'API restituisce null per un tipo primitivo. Verifica che il backend ritorni sempre un valore valido.
+
+### Tipi primitivi non funzionano (Dart)
+✅ **RISOLTO** - Ora il generatore gestisce correttamente String, int, bool, double con conversioni automatiche.
+
+## 🛠️ Sviluppo
+
+```bash
+# Clone repository
+git clone <repo-url>
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test local
+npm run debug-angular
+npm run debug-nextjs
+npm run debug-flutter
+```
+
+## 📝 Script NPM
+
+| Script | Descrizione |
+|--------|-------------|
+| `npm run build` | Compila TypeScript e copia templates |
+| `npm run debug-angular` | Test con target Angular |
+| `npm run debug-nextjs` | Test con target Next.js |
+| `npm run debug-flutter` | Test con target Flutter |
+| `npm run deploy` | Pubblica su npm |
+
+## 🤝 Contribuire
+
+Contributi benvenuti! Per favore:
+1. Fai fork del progetto
+2. Crea un branch per la tua feature (`git checkout -b feature/amazing-feature`)
+3. Commit dei cambiamenti (`git commit -m 'Add amazing feature'`)
+4. Push del branch (`git push origin feature/amazing-feature`)
+5. Apri una Pull Request
+
+## 📄 Licenza
+
+ISC License - vedi file LICENSE per dettagli
+
+## 🙏 Crediti
+
+Sviluppato da DeVLearninG Team
+
+---
+
+**Note**: Questo tool è in sviluppo attivo. Per bug o feature request, apri una issue su GitHub.