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>
This commit is contained in:
d.viti
274
web/docs/argocd-values-guide.md
Normal file
274
web/docs/argocd-values-guide.md
Normal file
@@ -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
|
||||
457
web/docs/swagger-documentation.md
Normal file
457
web/docs/swagger-documentation.md
Normal file
@@ -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/)
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user