Swagger API Generator

Generatore automatico di client API e modelli per Angular, Next.js e Flutter/Dart da specifiche Swagger/OpenAPI.

🎯 Caratteristiche

• ✅ 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

📦 Installazione

npm install @devlearning/swagger-generator --save-dev

🚀 Utilizzo

Da linea di comando

npx swgen --url <swagger-url> --output <output-dir> --target <angular|next|flutter> [opzioni]

Esempi

Angular

npx swgen \
  --url http://localhost:5000/swagger/v1/swagger.json \
  --output src/app/core/autogen \
  --target angular \
  --dateTimeLibrary moment

Next.js

npx swgen \
  --url https://api.example.com/swagger.json \
  --output src/lib/api \
  --target next \
  --dateTimeLibrary date-fns

Flutter/Dart

npx swgen \
  --url http://localhost:5000/swagger/v1/swagger.json \
  --output lib/core/api \
  --target flutter \
  --package my_app_name

Opzioni

| 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) | ❌ | - | | --api-client-name | -a | Nome classe API unificata | ❌ | - |

🆕 API Client Unificata

Di default, il generatore crea classi API separate raggruppate per tag Swagger. Con l'opzione --api-client-name, puoi generare una singola classe unificata contenente tutti i metodi API.

Esempio: Flutter con classe unificata

npx swgen \
  --url http://localhost:5000/swagger/v1/swagger.json \
  --output lib/core/api \
  --target flutter \
  --package my_app \
  --api-client-name ApiClient

Genera:

// lib/core/api/api_client.dart
class ApiClient {
  // Tutti i metodi API in una singola classe
  Future<User> getUser(String id) async { ... }
  Future<List<Product>> getProducts() async { ... }
  Future<void> createOrder(Order order) async { ... }
  // ...
}

Senza --api-client-name (comportamento predefinito)

Genera classi separate per tag:

// lib/core/api/users_api.dart
class UsersApi { ... }

// lib/core/api/products_api.dart  
class ProductsApi { ... }

// lib/core/api/orders_api.dart
class OrdersApi { ... }

Quando usare la classe unificata?

• ✅ Progetti piccoli/medi con pochi endpoint
• ✅ Quando preferisci un singolo punto di accesso alle API
• ✅ Per semplificare la dependency injection

Quando usare classi separate?

• ✅ Progetti grandi con molti endpoint
• ✅ Quando vuoi separare le responsabilità per dominio
• ✅ Per team diversi che lavorano su moduli diversi

📁 Struttura File Generati

Angular

output/
├── models/
│   ├── user.model.ts
│   ├── product.model.ts
│   └── ...
└── api/
    ├── user.api.ts
    ├── product.api.ts
    └── ...

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:

import { Injectable } from '@angular/core';
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:

import { User } from './autogen/models/user.model';
import { UserApi } from './autogen/api/user.api';

Next.js

import { getUsers } from '@/lib/api/user-api';
import { User } from '@/lib/api/models/user';

export async function UsersPage() {
  const users = await getUsers();
  // ...
}

Flutter/Dart

import 'package:my_app/core/api/user/api/user_api.dart';
import 'package:my_app/core/api/user/models/user.dart';

final userApi = UserApi();
final users = await userApi.getUsers();

🐛 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

# 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.