api7-demo/web/docs/swagger-documentation.md

title, description

title	description
Swagger & OpenAPI Documentation	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/
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	Interactive documentation
ReDoc	/api/redoc	Clean documentation style
OpenAPI JSON	/api/openapi.json	Raw OpenAPI schema
API Root	/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:

{
  "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:

{
  "status": "healthy",
  "service": "api",
  "timestamp": "2025-10-09T16:00:00"
}

GET /ready

Kubernetes readiness probe endpoint.

Response:

{
  "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

[
  {
    "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:

{
  "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

{
  "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:

{
  "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:

{
  "prompt": "What is API7 Enterprise?",
  "max_tokens": 150,
  "temperature": 0.7,
  "model": "videogame-expert"
}

Response: 200 OK

{
  "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:

{
  "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:

{
  "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
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:

   {
     "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
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:

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:

# Import OpenAPI spec
File → Import → https://commandware.it/api/openapi.json

Insomnia:

# Import OpenAPI spec
Dashboard → Import/Export → https://commandware.it/api/openapi.json

OpenAPI Generator:

# 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 - Set up the development environment
• API7 Configuration - Configure API7 Gateway
• Ingress & Routing - Configure traffic routing
• Troubleshooting - Common issues and solutions

---

References

• FastAPI Documentation
• OpenAPI Specification
• Swagger UI
• ReDoc