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

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

🚀 Utilizzo

$3

`bash
npx swgen --url --output --target [opzioni]
`

$3

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

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

$3

| 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 | ❌ | - |

$3

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

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

Genera:
`dart
// lib/core/api/api_client.dart
class ApiClient {
// Tutti i metodi API in una singola classe
Future getUser(String id) async { ... }
Future> getProducts() async { ... }
Future createOrder(Order order) async { ... }
// ...
}
`

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

Genera classi separate per tag:
`dart
// 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

$3


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

$3

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

$3

`
lib/output/
├── user/
│ ├── models/
│ │ └── user.dart
│ └── api/
│ └── user_api.dart
└── product/
├── models/
│ └── product.dart
└── api/
└── product_api.dart
`

🔧 Integrazione nel Progetto

$3

1. Crea un service wrapper:

`typescript
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:

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

$3

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

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

$3

`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

$3


Il documento Swagger non è valido. Verifica:
- Presenza di openApi version
- Presenza di paths object
- Struttura corretta delle definizioni

$3

L'API restituisce null per un tipo primitivo. Verifica che il backend ritorni sempre un valore valido.

$3

✅ RISOLTO - Ora il generatore gestisce correttamente String, int, bool, double con conversioni automatiche.

🛠️ Sviluppo

`bash


Clone repository

git clone

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.