Move all documentation to web/docs for MkDocs integration

Moved all documentation files into web/docs/ directory for proper
MkDocs integration and updated navigation structure.

Changes:
========

1. Documentation Structure:
   - Moved SWAGGER-WEB-UPDATE.md → web/docs/swagger-documentation.md
   - Moved ARGOCD-VALUES-UPDATE.md → web/docs/argocd-values-guide.md
   - Formatted both files with MkDocs frontmatter and structure

2. MkDocs Navigation (web/mkdocs.yml):
   - Updated site_url to https://commandware.it/docs
   - Added new section "API Documentation" with Swagger guide
   - Added "ArgoCD Values Guide" to Configuration section
   - Enhanced markdown extensions:
     * Added mermaid diagram support
     * Added task lists
     * Added emoji support
     * Added code annotations
   - Added navigation features (instant, tabs, sections)
   - Added tags plugin
   - Improved copyright notice

3. Swagger Documentation (web/docs/swagger-documentation.md):
   - Complete guide to Swagger UI, ReDoc, and OpenAPI
   - Access instructions via web interface and direct links
   - API overview with architecture diagram
   - Detailed endpoint documentation for all groups:
     * Root (/)
     * Health (/health, /ready)
     * Items CRUD (/items/*)
     * Users (/users/*)
     * LLM (/llm/*)
   - Interactive testing examples
   - OpenAPI specification download instructions
   - Tools integration (Postman, Insomnia, OpenAPI Generator)
   - Cross-references to other documentation pages

4. ArgoCD Values Guide (web/docs/argocd-values-guide.md):
   - Comprehensive guide for updating values.yaml in ArgoCD
   - All modifications explained (before/after)
   - Step-by-step application instructions
   - Verification commands
   - Security best practices

New MkDocs Navigation:
======================
- Home
- Getting Started
- Architecture
  - Overview
  - Kubernetes Resources
- Configuration
  - API7 Gateway
  - Ingress & Routing
  - Service Discovery
  - Secret Management
  - ArgoCD Values Guide ← NEW
  - CI/CD Pipeline
- API Documentation ← NEW SECTION
  - Swagger & OpenAPI
- Troubleshooting

All documentation is now centralized in web/docs/ and accessible
through MkDocs at https://commandware.it/docs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

web/docs/argocd-values-guide.md

@@ -0,0 +1,274 @@
+# ArgoCD Values Update Guide
+
+Questo documento descrive le modifiche da applicare al `values.yaml` in ArgoCD.
+
+## 📋 Modifiche Principali
+
+### 1. Service Discovery - DISABILITATO
+
+**Prima:**
+```yaml
+api7:
+  serviceDiscovery:
+    enabled: true
+```
+
+**Dopo:**
+```yaml
+api7:
+  serviceDiscovery:
+    enabled: false  # Disabled until Service Registry is configured in API7 Dashboard
+    namespace: ""
+```
+
+**Motivo:** Service discovery richiede la configurazione di un Service Registry nel Dashboard API7 Enterprise. Finché non viene configurato, ADC sync fallisce con errore `service registry not found`.
+
+---
+
+### 2. Existing Secret - CONFIGURATO
+
+**Prima:**
+```yaml
+api7:
+  gateway:
+    existingSecret: ""
+```
+
+**Dopo:**
+```yaml
+api7:
+  gateway:
+    # Use existing secret for production (recommended)
+    # The secret api7-credentials already exists with the correct admin key
+    existingSecret: "api7-credentials"
+    existingSecretKeys:
+      adminUrl: admin-url
+      adminKey: admin-key
+      group: gateway-group
+```
+
+**Motivo:** Il Secret `api7-credentials` esiste già nel namespace `api7ee` con la chiave admin corretta. Usarlo evita di creare un nuovo Secret vuoto.
+
+---
+
+### 3. Gateway Namespace - AGGIUNTO
+
+**Prima:**
+```yaml
+api7:
+  gateway:
+    gatewayService: gateway-0-1759393614-gateway
+```
+
+**Dopo:**
+```yaml
+api7:
+  gateway:
+    gatewayService: gateway-0-1759393614-gateway
+    gatewayNamespace: api7ee
+```
+
+---
+
+### 4. ADC Resources - CONFIGURATE
+
+```yaml
+api7:
+  adc:
+    resources:
+      limits:
+        cpu: 500m
+        memory: 256Mi
+      requests:
+        cpu: 100m
+        memory: 128Mi
+```
+
+---
+
+### 5. Ingress Configuration - AGGIORNATA
+
+**Prima:**
+```yaml
+ingress:
+  annotations:
+    nginx.ingress.kubernetes.io/rewrite-target: /
+  hosts:
+    - host: commandware.it
+      paths:
+        - path: /
+          gateway:
+            serviceName: gateway-0-1759393614-gateway
+            port: 80
+        - path: /api
+          gateway:
+            serviceName: gateway-0-1759393614-gateway
+            port: 80
+  tls:
+    - secretName: api7ee-demo-tls
+```
+
+**Dopo:**
+```yaml
+ingress:
+  className: nginx
+  annotations:
+    cert-manager.io/cluster-issuer: cloudflare-acme-prod
+  hosts:
+    - host: commandware.it
+      paths:
+        - path: /
+          pathType: Prefix
+          gateway:
+            serviceName: gateway-0-1759393614-gateway
+            port: 80
+            namespace: api7ee
+  tls:
+    - secretName: api7ee-tls
+      hosts:
+        - commandware.it
+```
+
+**Modifiche:**
+- Rimossa annotation `nginx.ingress.kubernetes.io/rewrite-target: /`
+- Aggiunta annotation `cert-manager.io/cluster-issuer`
+- Un solo path `/` invece di due path separati (`/` e `/api`)
+- Aggiunto `namespace: api7ee` al gateway
+- Cambiato `secretName` da `api7ee-demo-tls` a `api7ee-tls`
+
+---
+
+### 6. TLS Configuration - COMPLETATA
+
+```yaml
+api7:
+  tls:
+    enabled: true
+    certManager:
+      enabled: true
+      issuer: cloudflare-acme-prod
+      issuerKind: ClusterIssuer
+    privateKey:
+      rotationPolicy: Always
+      algorithm: RSA
+      size: 2048
+    duration: 2160h  # 90 days
+    renewBefore: 720h  # 30 days before expiry
+```
+
+---
+
+## 🔄 Come Applicare le Modifiche
+
+### Opzione 1: Interfaccia Web ArgoCD
+
+1. Accedi ad ArgoCD Dashboard
+2. Seleziona l'applicazione `api7ee-demo`
+3. Clicca su "APP DETAILS" → "PARAMETERS"
+4. Modifica i valori come sopra indicato
+5. Clicca "SAVE"
+6. Clicca "SYNC" per applicare le modifiche
+
+### Opzione 2: Via CLI
+
+```bash
+# Edit application
+kubectl edit application -n argocd api7ee-demo
+
+# O usa ArgoCD CLI
+argocd app set api7ee-demo --values /path/to/updated-values.yaml
+argocd app sync api7ee-demo
+```
+
+### Opzione 3: Usa il values.yaml aggiornato
+
+Il file `values.yaml` nella root del progetto è già stato aggiornato con tutte le modifiche.
+Puoi copiarlo direttamente nella configurazione ArgoCD.
+
+---
+
+## ✅ Verifica Post-Sync
+
+Dopo la sincronizzazione, verifica che tutto funzioni:
+
+### 1. Check ConfigMap
+```bash
+kubectl get configmap -n api7ee api7ee-demo-api7ee-demo-k8s-adc-config \
+  -o jsonpath='{.data.adc-config\.yaml}' | grep "discovery_type"
+```
+**Risultato atteso:** Nessun output (service discovery disabilitato)
+
+### 2. Check Secret
+```bash
+kubectl get secret -n api7ee api7ee-demo-api7ee-demo-k8s-api7-admin \
+  -o jsonpath='{.data.admin-key}' | base64 -d | wc -c
+```
+**Risultato atteso:** `88` (chiave presente)
+
+### 3. Check ADC Sync Job
+```bash
+kubectl logs -n api7ee job/api7ee-demo-api7ee-demo-k8s-adc-sync --tail=20
+```
+**Risultato atteso:**
+```
+[ADC] › ✔  success   Sync configuration
+[ADC] › ★  star      All is well, see you next time!
+```
+
+### 4. Test Routing
+```bash
+# Test web
+curl -I https://commandware.it/
+
+# Test API
+curl -I https://commandware.it/api/health
+```
+**Risultato atteso:** HTTP 200 o 405 (metodi funzionanti)
+
+---
+
+## 📝 Note Importanti
+
+### Service Discovery
+Per riabilitare service discovery in futuro:
+
+1. **Configura Service Registry nel Dashboard API7:**
+   - Accedi al Dashboard: `https://api7ee3-0-1759339083-dashboard:7443`
+   - Vai a: Gateway Groups → Service Registries
+   - Aggiungi: Kubernetes Service Registry
+   - Configura: API Server URL e Token
+
+2. **Abilita nel values.yaml:**
+   ```yaml
+   api7:
+     serviceDiscovery:
+       enabled: true
+   ```
+
+3. **Sync ArgoCD**
+
+### Secret Management
+Il Secret `api7-credentials` contiene:
+- `admin-url`: URL del Dashboard API7
+- `admin-key`: Chiave di autenticazione (88 caratteri)
+- `gateway-group`: Nome del gateway group (`default`)
+
+Per ruotare le credenziali:
+```bash
+kubectl patch secret -n api7ee api7-credentials \
+  -p '{"data":{"admin-key":"<new-base64-encoded-key>"}}'
+```
+
+---
+
+## 🔗 Riferimenti
+
+- [Service Discovery Guide](web/docs/service-discovery.md)
+- [Secret Management Guide](web/docs/secret-management.md)
+- [Ingress & Routing Guide](web/docs/ingress-routing.md)
+- [API7 Enterprise Docs](https://docs.api7.ai/enterprise/)
+
+---
+
+**Data aggiornamento:** 2025-10-09
+**Versione Chart:** api7ee-demo-k8s-0.1.0

web/docs/swagger-documentation.md

@@ -0,0 +1,457 @@
+---
+title: Swagger & OpenAPI Documentation
+description: Complete guide to API documentation with Swagger UI, ReDoc, and OpenAPI
+---
+
+# Swagger & OpenAPI Documentation
+
+Complete documentation for the API7 Enterprise Demo API with interactive Swagger UI.
+
+## Overview
+
+The API provides comprehensive documentation through multiple formats:
+
+- **Swagger UI** - Interactive API documentation and testing
+- **ReDoc** - Clean, responsive API documentation
+- **OpenAPI JSON** - Machine-readable API specification
+
+## Access Documentation
+
+### Via Web Interface
+
+1. Navigate to [https://commandware.it/](https://commandware.it/)
+2. Click **📚 API Docs** in the navigation menu
+3. Choose your preferred format:
+    - **Swagger UI** - For interactive testing
+    - **ReDoc** - For reading documentation
+    - **OpenAPI JSON** - For programmatic access
+    - **API Root** - For API metadata
+
+### Direct Links
+
+| Format | URL | Description |
+|--------|-----|-------------|
+| **Swagger UI** | [/api/docs](https://commandware.it/api/docs) | Interactive documentation |
+| **ReDoc** | [/api/redoc](https://commandware.it/api/redoc) | Clean documentation style |
+| **OpenAPI JSON** | [/api/openapi.json](https://commandware.it/api/openapi.json) | Raw OpenAPI schema |
+| **API Root** | [/api/](https://commandware.it/api/) | API information |
+
+---
+
+## API Overview
+
+### Architecture
+
+```
+Client → Ingress (NGINX) → API7 Gateway → Backend API
+                              ↓
+                          • Rate Limiting
+                          • CORS
+                          • Proxy Rewrite (/api → /)
+                          • Service Discovery
+```
+
+### Features
+
+- ✅ **CRUD Operations** - Items and Users management
+- ✅ **LLM Integration** - AI-powered chat with OpenAI-compatible API
+- ✅ **Health Checks** - Kubernetes-ready liveness and readiness probes
+- ✅ **Rate Limiting** - Standard (100 req/min) and AI-based (100 tokens/min)
+- ✅ **CORS** - Cross-origin resource sharing enabled
+- ✅ **Proxy Rewrite** - Automatic /api prefix removal by API7 Gateway
+
+### Rate Limiting
+
+| Endpoint Type | Limit | Window | Strategy |
+|---------------|-------|--------|----------|
+| Standard API (`/items`, `/users`) | 100 requests | 60 seconds | Per IP address |
+| LLM API (`/llm/*`) | 100 tokens | 60 seconds | AI-based (total tokens) |
+
+---
+
+## Endpoint Groups
+
+### 🏠 Root
+
+#### `GET /`
+
+API information with navigation links.
+
+**Response:**
+```json
+{
+  "message": "Welcome to API7 Enterprise Demo API",
+  "version": "1.0.0",
+  "documentation": {
+    "swagger": "/docs",
+    "redoc": "/redoc",
+    "openapi": "/openapi.json"
+  },
+  "endpoints": {
+    "items": "/items",
+    "users": "/users",
+    "llm": "/llm"
+  },
+  "timestamp": "2025-10-09T16:00:00"
+}
+```
+
+---
+
+### 💚 Health
+
+#### `GET /health`
+
+Kubernetes liveness probe endpoint.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "service": "api",
+  "timestamp": "2025-10-09T16:00:00"
+}
+```
+
+#### `GET /ready`
+
+Kubernetes readiness probe endpoint.
+
+**Response:**
+```json
+{
+  "status": "ready",
+  "service": "api",
+  "timestamp": "2025-10-09T16:00:00"
+}
+```
+
+---
+
+### 📦 Items (CRUD)
+
+Full CRUD operations for items inventory management.
+
+#### `GET /items`
+
+List all items in inventory.
+
+**Rate Limit:** 100 requests per 60 seconds per IP
+
+**Response:** `200 OK`
+```json
+[
+  {
+    "id": 1,
+    "name": "Laptop",
+    "description": "High-performance laptop",
+    "price": 999.99,
+    "in_stock": true
+  }
+]
+```
+
+#### `GET /items/{id}`
+
+Get a specific item by ID.
+
+**Parameters:**
+- `id` (path, integer, required) - Item ID
+
+**Responses:**
+- `200 OK` - Item details
+- `404 Not Found` - Item not found
+
+#### `POST /items`
+
+Create a new item.
+
+**Request Body:**
+```json
+{
+  "name": "Laptop",
+  "description": "High-performance laptop",
+  "price": 999.99,
+  "in_stock": true
+}
+```
+
+**Response:** `201 Created`
+
+#### `PUT /items/{id}`
+
+Update an existing item.
+
+**Parameters:**
+- `id` (path, integer, required) - Item ID
+
+**Response:** `200 OK`
+
+#### `DELETE /items/{id}`
+
+Delete an item.
+
+**Parameters:**
+- `id` (path, integer, required) - Item ID
+
+**Response:** `200 OK`
+```json
+{
+  "message": "Item deleted successfully",
+  "id": 1
+}
+```
+
+---
+
+### 👥 Users
+
+User management operations.
+
+#### `GET /users`
+
+List all users.
+
+**Rate Limit:** 100 requests per 60 seconds per IP
+
+#### `GET /users/{id}`
+
+Get a specific user by ID.
+
+#### `POST /users`
+
+Create a new user.
+
+**Request Body:**
+```json
+{
+  "username": "john_doe",
+  "email": "john@example.com",
+  "active": true
+}
+```
+
+**Response:** `201 Created`
+
+---
+
+### 🤖 LLM (AI Integration)
+
+AI-powered chat endpoints with OpenAI-compatible API.
+
+#### `POST /llm/chat`
+
+Chat completion with AI rate limiting.
+
+**Rate Limit:** 100 tokens per 60 seconds (AI-based)
+
+**Request Body:**
+```json
+{
+  "prompt": "What is API7 Enterprise?",
+  "max_tokens": 150,
+  "temperature": 0.7,
+  "model": "videogame-expert"
+}
+```
+
+**Response:** `200 OK`
+```json
+{
+  "response": "API7 Enterprise is...",
+  "tokens_used": 45,
+  "model": "videogame-expert",
+  "timestamp": "2025-10-09T16:00:00"
+}
+```
+
+**Errors:**
+- `429 Too Many Requests` - Rate limit exceeded (100 tokens per 60 seconds)
+- `500 Internal Server Error` - LLM service error
+
+#### `GET /llm/models`
+
+List available LLM models.
+
+**Response:**
+```json
+{
+  "models": [
+    {
+      "id": "videogame-expert",
+      "name": "Videogame Expert",
+      "max_tokens": 4096,
+      "provider": "Open WebUI",
+      "description": "Specialized model for videogame-related questions"
+    }
+  ],
+  "default_model": "videogame-expert",
+  "provider": "Open WebUI"
+}
+```
+
+#### `GET /llm/health`
+
+LLM service health check.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "service": "llm-api",
+  "provider": "Open WebUI",
+  "endpoint": "http://localhost/api",
+  "default_model": "videogame-expert",
+  "rate_limit": {
+    "enabled": true,
+    "limit": 100,
+    "window": "60 seconds",
+    "strategy": "total_tokens",
+    "managed_by": "API7 Gateway (ai-rate-limiting plugin)"
+  }
+}
+```
+
+---
+
+## Using Swagger UI
+
+### Interactive Testing
+
+1. Navigate to [/api/docs](https://commandware.it/api/docs)
+2. Browse available endpoints organized by groups
+3. Click **"Try it out"** on any endpoint
+4. Fill in parameters and request body
+5. Click **"Execute"** to test the API
+6. View response with status code, headers, and body
+
+### Example: Testing Items API
+
+1. Go to **Items** section
+2. Click on `GET /items`
+3. Click **"Try it out"**
+4. Click **"Execute"**
+5. View the response with all items
+
+### Example: Creating an Item
+
+1. Go to **Items** section
+2. Click on `POST /items`
+3. Click **"Try it out"**
+4. Modify the request body:
+   ```json
+   {
+     "name": "New Laptop",
+     "description": "Gaming laptop",
+     "price": 1499.99,
+     "in_stock": true
+   }
+   ```
+5. Click **"Execute"**
+6. View `201 Created` response with the new item
+
+---
+
+## Using ReDoc
+
+### Clean Documentation
+
+1. Navigate to [/api/redoc](https://commandware.it/api/redoc)
+2. Browse the clean, three-column layout:
+    - **Left**: Navigation menu
+    - **Center**: Endpoint details
+    - **Right**: Code examples
+3. Search for specific endpoints
+4. Download OpenAPI spec
+
+### Features
+
+- ✅ Responsive design
+- ✅ Search functionality
+- ✅ Code examples in multiple languages
+- ✅ Print-friendly
+- ✅ Mobile-friendly
+
+---
+
+## OpenAPI Specification
+
+### Download Schema
+
+Access the raw OpenAPI 3.0 specification:
+
+```bash
+curl https://commandware.it/api/openapi.json > openapi.json
+```
+
+### Use Cases
+
+- **Code Generation** - Generate client SDKs
+- **API Testing** - Import into Postman/Insomnia
+- **Validation** - Validate requests/responses
+- **Documentation** - Generate custom documentation
+
+### Tools Integration
+
+**Postman:**
+```bash
+# Import OpenAPI spec
+File → Import → https://commandware.it/api/openapi.json
+```
+
+**Insomnia:**
+```bash
+# Import OpenAPI spec
+Dashboard → Import/Export → https://commandware.it/api/openapi.json
+```
+
+**OpenAPI Generator:**
+```bash
+# Generate Python client
+openapi-generator-cli generate \
+  -i https://commandware.it/api/openapi.json \
+  -g python \
+  -o ./api-client
+```
+
+---
+
+## API Changes
+
+### Enhanced Documentation
+
+All endpoints now include:
+
+- ✅ Detailed summaries and descriptions
+- ✅ Parameter explanations with examples
+- ✅ Response descriptions with status codes
+- ✅ Error responses (404, 429, 500)
+- ✅ Rate limiting information
+- ✅ Request/response examples
+
+### Model Enhancements
+
+All Pydantic models include:
+
+- ✅ Field descriptions
+- ✅ Validation rules (min_length, gt, ge, le)
+- ✅ Schema examples
+- ✅ Default values
+
+---
+
+## Next Steps
+
+- [Getting Started](../getting-started.md) - Set up the development environment
+- [API7 Configuration](../api7-configuration.md) - Configure API7 Gateway
+- [Ingress & Routing](../ingress-routing.md) - Configure traffic routing
+- [Troubleshooting](../troubleshooting.md) - Common issues and solutions
+
+---
+
+## References
+
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+- [OpenAPI Specification](https://swagger.io/specification/)
+- [Swagger UI](https://swagger.io/tools/swagger-ui/)
+- [ReDoc](https://redocly.com/redoc/)

web/mkdocs.yml

@@ -1,7 +1,7 @@
 site_name: API7 Enterprise Demo Documentation
 site_description: Complete documentation for API7 Enterprise Gateway demo deployment
 site_author: CommandWare
-site_url: https://demo.commandware.it/docs
+site_url: https://commandware.it/docs
 docs_dir: docs
 
 theme:
@@ -24,9 +24,11 @@ theme:
     - navigation.sections
     - navigation.expand
     - navigation.top
+    - navigation.instant
     - search.suggest
     - search.highlight
     - content.code.copy
+    - content.code.annotate
   icon:
     repo: fontawesome/brands/git-alt
 
@@ -44,15 +46,24 @@ nav:
       - Ingress & Routing: ingress-routing.md
       - Service Discovery: service-discovery.md
       - Secret Management: secret-management.md
+      - ArgoCD Values Guide: argocd-values-guide.md
       - CI/CD Pipeline: cicd-pipeline.md
+  - API Documentation:
+      - Swagger & OpenAPI: swagger-documentation.md
   - Troubleshooting: troubleshooting.md
 
 markdown_extensions:
   - admonition
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.highlight:
       anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.tabbed:
@@ -62,15 +73,24 @@ markdown_extensions:
   - md_in_html
   - toc:
       permalink: true
+  - def_list
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
 
 plugins:
   - search
+  - tags
 
 extra:
   social:
     - icon: fontawesome/brands/git-alt
       link: https://git.commandware.com/demos/api7-demo
+      name: Git Repository
   version:
     provider: mike
+  generator: false
 
-copyright: Copyright © 2025 CommandWare
+copyright: Copyright © 2025 CommandWare | Powered by API7 Enterprise