cubenet_backend/SWAGGER_GUIDE.md

# 🌐 Swagger UI Guide - Полный взаимодействие с API

## 📍 Где находится Swagger UI

```
http://localhost:8000/swagger-ui.html
http://localhost:8000/swagger-ui/          (альтернативно)
```

## 🚀 Быстрый старт (3 шага)

### Шаг 1: Откройте 3 терминала

**Terminal 1 - User Service (gRPC сервер):**
```bash
cd /hdd/dev/cubenet_backend
cargo run -p user_service
```

**Terminal 2 - API Layer (gRPC клиент):**
```bash
cd /hdd/dev/cubenet_backend
cargo run -p api
```

**Terminal 3 - API Gateway (REST + Swagger):**
```bash
cd /hdd/dev/cubenet_backend
cargo run -p api_gateway
```

### Шаг 2: Проверьте что все запустилось

**Terminal 1 output:**
```
🚀 User Service listening on 0.0.0.0:13001
```

**Terminal 2 output:**
```
🚀 API listening on 0.0.0.0:8001
Connected to user_service at 127.0.0.1:13001
```

**Terminal 3 output:**
```
🚀 API Gateway listening on 0.0.0.0:8000
```

### Шаг 3: Откройте браузер

```
http://localhost:8000/swagger-ui.html
```

## 🎨 Swagger UI - Интерфейс

Когда откроете Swagger UI, вы увидите:

```
┌─────────────────────────────────────────────┐
│          Cubenet API Documentation          │
│                                             │
│ Servers: http://localhost:8000              │
│                                             │
├─────────────────────────────────────────────┤
│ GET    /health         Check API health    │
│ POST   /users          Create user          │
│ GET    /users          Get all users        │
│                                             │
└─────────────────────────────────────────────┘
```

## 📋 API Endpoints

### 1. Health Check
```
GET /health
```

**Response:**
```json
{
  "status": "ok"
}
```

### 2. Create User
```
POST /users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}
```

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2024-01-20T12:34:56Z"
}
```

### 3. Get All Users
```
GET /users
```

**Response:**
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Doe",
    "email": "john@example.com",
    "created_at": "2024-01-20T12:34:56Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "created_at": "2024-01-20T12:35:00Z"
  }
]
```

## 🎯 Как использовать Swagger UI

### Способ 1: Нажать "Try it out"

1. Найдите endpoint в списке
2. Нажмите на него (разворется)
3. Нажмите кнопку **"Try it out"**
4. Заполните параметры/тело
5. Нажмите **"Execute"**
6. Смотрите результат

### Способ 2: Просмотр документации

1. Кликните на endpoint
2. Смотрите:
   - Описание (Description)
   - Параметры (Parameters)
   - Примеры (Examples)
   - Коды ошибок (Responses)

## 💻 Примеры запросов (из терминала)

### Проверить здоровье
```bash
curl http://localhost:8000/health
```

**Output:**
```json
{"status":"ok"}
```

### Создать пользователя
```bash
curl -X POST http://localhost:8000/users \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com"
  }'
```

**Output:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2024-01-20T12:34:56Z"
}
```

### Получить всех пользователей
```bash
curl http://localhost:8000/users
```

**Output:**
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Doe",
    "email": "john@example.com",
    "created_at": "2024-01-20T12:34:56Z"
  }
]
```

## 📊 Архитектура потока запроса

```
┌──────────────────────────────────────────────────────────┐
│           Браузер с Swagger UI                           │
│          http://localhost:8000                           │
└───────────────────────┬──────────────────────────────────┘
                        │
                        │ REST API запрос
                        ↓
┌──────────────────────────────────────────────────────────┐
│              API Gateway (Axum)                          │
│          http://localhost:8000                           │
│  - Генерирует Swagger UI                                │
│  - Обрабатывает REST запросы                            │
│  - Логирует все действия пользователей                  │
└───────────────────────┬──────────────────────────────────┘
                        │
                        │ gRPC запрос
                        ↓
┌──────────────────────────────────────────────────────────┐
│              API Layer (gRPC Client)                     │
│          http://localhost:8001                          │
│  - Преобразует REST → gRPC                              │
│  - Логирует действия через audit_logger                │
└───────────────────────┬──────────────────────────────────┘
                        │
                        │ gRPC запрос
                        ↓
┌──────────────────────────────────────────────────────────┐
│           User Service (gRPC Server)                     │
│          http://localhost:13001                         │
│  - Обрабатывает бизнес логику                          │
│  - Работает с данными пользователей                    │
└──────────────────────────────────────────────────────────┘
```

## 🔍 Типичные сценарии использования

### Сценарий 1: Тестирование новых endpoints

1. Откройте Swagger UI
2. Найдите новый endpoint
3. Нажмите "Try it out"
4. Введите тестовые данные
5. Нажмите "Execute"
6. Проверьте результат

### Сценарий 2: Документирование API

- Swagger UI автоматически генерирует документацию
- Все endpoints видны с примерами
- Можно делать screenshot для документации
- Можно делиться ссылкой на Swagger

### Сценарий 3: Интеграция для клиентов

- Отправьте ссылку: `http://localhost:8000/swagger-ui.html`
- Клиенты видят полную документацию API
- Клиенты видят примеры запросов/ответов
- Клиенты видят все типы ошибок

### Сценарий 4: Отладка проблем

1. Проверьте Swagger UI видит ли endpoint
2. Попробуйте "Try it out"
3. Смотрите ошибку в Response
4. Проверьте Terminal 3 (api_gateway логи)

## ⚙️ Как Swagger генерируется

### API Gateway добавляет Swagger (api_gateway/src/main.rs):

```rust
use utoipa::Utoipa;
use utoipa_swagger_ui::SwaggerUi;

// 1. Генерирует OpenAPI spec
// 2. Сервирует Swagger UI на /swagger-ui.html
// 3. Автоматически документирует endpoints
```

## 🛠️ Добавление нового endpoint в Swagger

### Шаг 1: Добавьте endpoint в API Gateway

```rust
use utoipa::path;

#[utoipa::path(
    post,
    path = "/users",
    request_body = CreateUserRequest,
    responses(
        (status = 200, description = "User created", body = User),
        (status = 400, description = "Invalid input")
    )
)]
pub async fn create_user(Json(req): Json<CreateUserRequest>) -> Json<User> {
    // implementation
}
```

### Шаг 2: Перекомпилируйте

```bash
cargo build -p api_gateway
```

### Шаг 3: Перезагрузите Swagger UI

```
http://localhost:8000/swagger-ui.html
```

Новый endpoint появится автоматически!

## 📊 Структуры данных в Swagger

### User
```json
{
  "id": "string (UUID)",
  "name": "string",
  "email": "string",
  "created_at": "string (ISO 8601 datetime)"
}
```

### CreateUserRequest
```json
{
  "name": "string (required)",
  "email": "string (required)"
}
```

### HealthResponse
```json
{
  "status": "string (always 'ok')"
}
```

## 🔗 Полезные ссылки

### Swagger UI
- http://localhost:8000/swagger-ui.html

### OpenAPI JSON Schema
- http://localhost:8000/api-docs.json

### Здоровье API
- http://localhost:8000/health

## 🐛 Troubleshooting

### Swagger не открывается

**Проблема:** Getting connection refused error

**Решение:**
1. Проверьте Terminal 3 (api_gateway) - должен быть запущен
2. Проверьте портрок 8000:
   ```bash
   lsof -i :8000
   ```
3. Если занят, измените порт в `api_gateway/src/main.rs`

### Endpoints не видны в Swagger

**Проблема:** Список endpoints пуст

**Решение:**
1. Проверьте что endpoints добавлены в `api_gateway/src/main.rs`
2. Проверьте что используется макрос `#[utoipa::path(...)]`
3. Перекомпилируйте:
   ```bash
   cargo clean -p api_gateway
   cargo build -p api_gateway
   ```

### Response ошибка при "Try it out"

**Проблема:** Запрос возвращает ошибку

**Решение:**
1. Проверьте Terminal 2 (api) логи - видны ошибки там
2. Проверьте Terminal 1 (user_service) логи
3. Убедитесь что все сервисы запущены
4. Проверьте структуру JSON тела запроса

## 📚 Документация

- [Utoipa (Swagger для Rust)](https://github.com/juhaku/utoipa)
- [OpenAPI Specification](https://spec.openapis.org/oas/v3.0.3)
- [Swagger UI Documentation](https://github.com/swagger-api/swagger-ui)

## ✨ Примеры использования

### Пример 1: Создание 3 пользователей

```bash
# User 1
curl -X POST http://localhost:8000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com"}'

# User 2
curl -X POST http://localhost:8000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Bob","email":"bob@example.com"}'

# User 3
curl -X POST http://localhost:8000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Charlie","email":"charlie@example.com"}'
```

### Пример 2: Получить всех пользователей

```bash
curl http://localhost:8000/users | jq .
```

### Пример 3: Проверить здоровье системы

```bash
curl http://localhost:8000/health | jq .
```

## 🎯 Итог

- **Swagger UI URL:** `http://localhost:8000/swagger-ui.html`
- **OpenAPI JSON:** `http://localhost:8000/api-docs.json`
- **Полностью автоматический:** Документация генерируется из кода
- **Интерактивный:** Можно тестировать API прямо из браузера
- **Всегда актуален:** Обновляется при каждом перезагрузке

---

**Status:** ✅ Ready to use