docs: enhance README with badges, TOC, Swagger/OpenAPI documentation

- Add shields.io badges for Python, FastAPI, License, Coverage, Tests
- Add Table of Contents for easy navigation
- Add Quick Start section with Docker
- Enhance OpenAPI documentation in main.py with detailed description
- Add VERIFICA_PROGETTO.md with complete PRD compliance report
- Update all API documentation links (Swagger UI, ReDoc, OpenAPI)
- Add API usage examples with curl commands
- Add client generation instructions

src/openrouter_monitor/main.py

@@ -40,13 +40,76 @@ async def lifespan(app: FastAPI):
 # Get project root directory
 PROJECT_ROOT = Path(__file__).parent.parent.parent
 
-# Create FastAPI app
+# Create FastAPI app with enhanced OpenAPI documentation
 app = FastAPI(
     title="OpenRouter API Key Monitor",
-    description="Monitor and manage OpenRouter API keys",
+    description="""
+    🚀 **OpenRouter API Key Monitor** - Applicazione web multi-utente per monitorare 
+    l'utilizzo delle API key della piattaforma OpenRouter.
+    
+    ## Funzionalità Principali
+    
+    - **🔐 Autenticazione**: Registrazione e login con JWT
+    - **🔑 Gestione API Key**: CRUD completo con cifratura AES-256
+    - **📊 Dashboard**: Statistiche aggregate, grafici, filtri avanzati
+    - **🔓 API Pubblica**: Accesso programmatico con token API
+    - **⚡ Sincronizzazione Automatica**: Background tasks ogni ora
+    
+    ## Documentazione
+    
+    - **Swagger UI**: `/docs` - Interfaccia interattiva per testare le API
+    - **ReDoc**: `/redoc` - Documentazione alternativa più leggibile
+    - **OpenAPI JSON**: `/openapi.json` - Schema OpenAPI completo
+    
+    ## Autenticazione
+    
+    Le API REST utilizzano autenticazione JWT Bearer:
+    ```
+    Authorization: Bearer <your-jwt-token>
+    ```
+    
+    Le API Pubbliche utilizzano token API:
+    ```
+    Authorization: Bearer <your-api-token>
+    ```
+    
+    ## Rate Limiting
+    
+    - API JWT: 30 richieste/minuto per IP
+    - API Token: 100 richieste/ora per token
+    """,
     version="1.0.0",
     debug=settings.debug,
     lifespan=lifespan,
+    docs_url="/docs",
+    redoc_url="/redoc",
+    openapi_url="/openapi.json",
+    openapi_tags=[
+        {
+            "name": "authentication",
+            "description": "Operazioni di autenticazione: registrazione, login, logout",
+        },
+        {
+            "name": "api-keys",
+            "description": "Gestione delle API key OpenRouter: CRUD operazioni",
+        },
+        {
+            "name": "api-tokens",
+            "description": "Gestione dei token API per accesso programmatico",
+        },
+        {
+            "name": "statistics",
+            "description": "Visualizzazione statistiche e dashboard",
+        },
+        {
+            "name": "Public API v1",
+            "description": "API pubbliche per integrazioni esterne (autenticazione con token API)",
+        },
+        {
+            "name": "web",
+            "description": "Pagine web HTML (interfaccia utente)",
+        },
+    ],
 )
 
 # Mount static files (before CSRF middleware to allow access without token)