13 KiB
13 KiB
🌐 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 сервер):
cd /hdd/dev/cubenet_backend
cargo run -p user_service
Terminal 2 - API Layer (gRPC клиент):
cd /hdd/dev/cubenet_backend
cargo run -p api
Terminal 3 - API Gateway (REST + Swagger):
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:
{
"status": "ok"
}
2. Create User
POST /users
Content-Type: application/json
{
"name": "John Doe",
"email": "john@example.com"
}
Response:
{
"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:
[
{
"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"
- Найдите endpoint в списке
- Нажмите на него (разворется)
- Нажмите кнопку "Try it out"
- Заполните параметры/тело
- Нажмите "Execute"
- Смотрите результат
Способ 2: Просмотр документации
- Кликните на endpoint
- Смотрите:
- Описание (Description)
- Параметры (Parameters)
- Примеры (Examples)
- Коды ошибок (Responses)
💻 Примеры запросов (из терминала)
Проверить здоровье
curl http://localhost:8000/health
Output:
{"status":"ok"}
Создать пользователя
curl -X POST http://localhost:8000/users \
-H "Content-Type: application/json" \
-d '{
"name": "John Doe",
"email": "john@example.com"
}'
Output:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-20T12:34:56Z"
}
Получить всех пользователей
curl http://localhost:8000/users
Output:
[
{
"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
- Откройте Swagger UI
- Найдите новый endpoint
- Нажмите "Try it out"
- Введите тестовые данные
- Нажмите "Execute"
- Проверьте результат
Сценарий 2: Документирование API
- Swagger UI автоматически генерирует документацию
- Все endpoints видны с примерами
- Можно делать screenshot для документации
- Можно делиться ссылкой на Swagger
Сценарий 3: Интеграция для клиентов
- Отправьте ссылку:
http://localhost:8000/swagger-ui.html - Клиенты видят полную документацию API
- Клиенты видят примеры запросов/ответов
- Клиенты видят все типы ошибок
Сценарий 4: Отладка проблем
- Проверьте Swagger UI видит ли endpoint
- Попробуйте "Try it out"
- Смотрите ошибку в Response
- Проверьте Terminal 3 (api_gateway логи)
⚙️ Как Swagger генерируется
API Gateway добавляет Swagger (api_gateway/src/main.rs):
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
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: Перекомпилируйте
cargo build -p api_gateway
Шаг 3: Перезагрузите Swagger UI
http://localhost:8000/swagger-ui.html
Новый endpoint появится автоматически!
📊 Структуры данных в Swagger
User
{
"id": "string (UUID)",
"name": "string",
"email": "string",
"created_at": "string (ISO 8601 datetime)"
}
CreateUserRequest
{
"name": "string (required)",
"email": "string (required)"
}
HealthResponse
{
"status": "string (always 'ok')"
}
🔗 Полезные ссылки
Swagger UI
OpenAPI JSON Schema
Здоровье API
🐛 Troubleshooting
Swagger не открывается
Проблема: Getting connection refused error
Решение:
- Проверьте Terminal 3 (api_gateway) - должен быть запущен
- Проверьте портрок 8000:
lsof -i :8000 - Если занят, измените порт в
api_gateway/src/main.rs
Endpoints не видны в Swagger
Проблема: Список endpoints пуст
Решение:
- Проверьте что endpoints добавлены в
api_gateway/src/main.rs - Проверьте что используется макрос
#[utoipa::path(...)] - Перекомпилируйте:
cargo clean -p api_gateway cargo build -p api_gateway
Response ошибка при "Try it out"
Проблема: Запрос возвращает ошибку
Решение:
- Проверьте Terminal 2 (api) логи - видны ошибки там
- Проверьте Terminal 1 (user_service) логи
- Убедитесь что все сервисы запущены
- Проверьте структуру JSON тела запроса
📚 Документация
✨ Примеры использования
Пример 1: Создание 3 пользователей
# 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: Получить всех пользователей
curl http://localhost:8000/users | jq .
Пример 3: Проверить здоровье системы
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