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

---
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/)