diff --git a/web/docs/argocd-values-guide.md b/web/docs/argocd-values-guide.md new file mode 100644 index 0000000..f865138 --- /dev/null +++ b/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":""}}' +``` + +--- + +## πŸ”— 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 diff --git a/web/docs/swagger-documentation.md b/web/docs/swagger-documentation.md new file mode 100644 index 0000000..23f7b6b --- /dev/null +++ b/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/) diff --git a/web/mkdocs.yml b/web/mkdocs.yml index 18f3b97..8fbf8e0 100644 --- a/web/mkdocs.yml +++ b/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