API_DOCUMENTATION.md

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

Введение

Этот проект предоставляет REST API для управления вакансиями с полной OpenAPI (Swagger) документацией.

Доступ к документации

После запуска приложения документация доступна по следующим адресам:

1. Swagger UI (интерактивная документация)

URL: http://localhost:8080/swagger-ui.html

Swagger UI предоставляет:

• Интерактивный интерфейс для тестирования API
• Возможность отправлять запросы прямо из браузера
• Визуализацию всех эндпоинтов с примерами
• Схемы данных для запросов и ответов

2. ReDoc (красивая документация для чтения)

URL: http://localhost:8080/redoc.html

ReDoc предлагает:

• Современный дизайн документации
• Удобную навигацию
• Читаемый формат для изучения API
• Поддержку поиска

3. OpenAPI спецификация (YAML)

URL: http://localhost:8080/openapi.yaml

Прямой доступ к OpenAPI спецификации в формате YAML:

• Можно импортировать в Postman
• Можно использовать для генерации клиентов
• Машиночитаемый формат

Основные возможности API

Эндпоинты

Метод	Путь	Описание
GET	/vacancy	Получить список вакансий с пагинацией
GET	/vacancy/search	🔍 Полнотекстовый поиск вакансий (10-100x быстрее)
GET	/vacancy/{id}	Получить конкретную вакансию
POST	/vacancy	Создать новую вакансию
PUT	/vacancy/{id}	Обновить вакансию
DELETE	/vacancy/{id}	Удалить вакансию

Примеры запросов

🔍 Полнотекстовый поиск вакансий

# Простой поиск
curl -X GET "http://localhost:8080/vacancy/search?q=PHP" \
  -H "Accept: application/json"

# Поиск по нескольким словам
curl -X GET "http://localhost:8080/vacancy/search?q=PHP%20разработчик" \
  -H "Accept: application/json"

# Поиск с пагинацией и сортировкой по релевантности
curl -X GET "http://localhost:8080/vacancy/search?q=developer&page=2&sort=relevance" \
  -H "Accept: application/json"

# Поиск с сортировкой по дате
curl -X GET "http://localhost:8080/vacancy/search?q=backend&sort=desc" \
  -H "Accept: application/json"

Параметры поиска:

• q (обязательный) - поисковый запрос (1-255 символов)
• page (опционально) - номер страницы (1-10000, по умолчанию: 1)
• sort (опционально) - сортировка: relevance (по умолчанию), asc, desc

Получить список вакансий

curl -X GET "http://localhost:8080/vacancy?page=1&sort=salary&order=desc" \
  -H "Accept: application/json"

Получить вакансию по ID

curl -X GET "http://localhost:8080/vacancy/1" \
  -H "Accept: application/json"

Создать вакансию

curl -X POST "http://localhost:8080/vacancy" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "PHP Developer",
    "description": "Требуется опытный разработчик",
    "salary": 150000,
    "additional_fields": {
      "company": "Tech Corp",
      "location": "Москва",
      "remote": true
    }
  }'

Обновить вакансию

curl -X PUT "http://localhost:8080/vacancy/1" \
  -H "Content-Type: application/json" \
  -d '{
    "salary": 180000
  }'

Удалить вакансию

curl -X DELETE "http://localhost:8080/vacancy/1" \
  -H "Accept: application/json"

Особенности

Полнотекстовый поиск

API поддерживает быстрый полнотекстовый поиск с использованием FULLTEXT индексов:

• PostgreSQL: tsvector с русской морфологией и GIN индексом
• MySQL: FULLTEXT индексы на полях title и description
• Ранжирование: автоматическая сортировка по релевантности
• Производительность: 10-100x быстрее обычного LIKE поиска
• Кеширование: результаты кешируются на 5 минут

Кеширование

API использует кеширование для повышения производительности:

• Список вакансий: кеш на 5 минут
• Отдельная вакансия: кеш на 10 минут
• Результаты поиска: кеш на 5 минут

Кеш автоматически инвалидируется при создании, обновлении или удалении вакансий.

Rate Limiting

API защищен от злоупотреблений с помощью rate limiting:

• Лимит: 100 запросов в час на IP адрес
• Поведение при превышении: HTTP 429 (Too Many Requests)

Настройки можно изменить в файле .env:

RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=3600

CORS

API поддерживает CORS для работы с frontend приложениями.

Настройка разрешенных доменов в .env:

CORS_ORIGIN=http://localhost:3000,https://yourdomain.com

Пагинация

Список вакансий поддерживает пагинацию:

• Размер страницы: 10 записей
• Параметры:
  • page - номер страницы (по умолчанию: 1)
  • sort - поле сортировки (salary, created_at)
  • order - направление (asc, desc)

Сортировка

Доступные поля для сортировки:

• salary - по зарплате
• created_at - по дате создания (по умолчанию)

Использование с инструментами

Postman

1. Импортируйте OpenAPI спецификацию:

   • File → Import
   • Вставьте URL: http://localhost:8080/openapi.yaml

2. Postman автоматически создаст коллекцию со всеми эндпоинтами

Insomnia

1. Create → Import from URL
2. Введите: http://localhost:8080/openapi.yaml
3. Insomnia создаст workspace с готовыми запросами

HTTPie

# Установка
pip install httpie

# Примеры использования
http GET http://localhost:8080/vacancy
http POST http://localhost:8080/vacancy title="Developer" salary:=150000 description="Job desc"

Генерация клиентов

Вы можете автоматически сгенерировать клиенты для различных языков используя OpenAPI Generator:

# JavaScript/TypeScript
npx @openapitools/openapi-generator-cli generate \
  -i http://localhost:8080/openapi.yaml \
  -g typescript-fetch \
  -o ./client

# Python
openapi-generator-cli generate \
  -i http://localhost:8080/openapi.yaml \
  -g python \
  -o ./python-client

# Java
openapi-generator-cli generate \
  -i http://localhost:8080/openapi.yaml \
  -g java \
  -o ./java-client

Валидация

API выполняет валидацию входных данных:

Обязательные поля при создании:

• title - название (строка, макс 255 символов)
• description - описание (строка)
• salary - зарплата (целое число > 0)

Опциональные поля:

• additional_fields - объект с дополнительными данными

Примеры ошибок валидации:

{
  "success": false,
  "message": "Ошибка при создании вакансии",
  "errors": {
    "title": ["Название вакансии не может быть пустым."],
    "salary": ["Зарплата должна быть целым числом."]
  }
}

Коды ответов

Код	Описание
200	Успешный запрос
201	Ресурс создан
400	Ошибка валидации
404	Ресурс не найден
429	Превышен лимит запросов
500	Внутренняя ошибка сервера

Тестирование API

Проект включает автоматические тесты API. Запуск:

# Все тесты
vendor/bin/codecept run api

# Конкретные тесты
vendor/bin/codecept run api VacancyCest
vendor/bin/codecept run api SearchCest
vendor/bin/codecept run api RateLimitingCest

# С подробным выводом
vendor/bin/codecept run api --debug

Дополнительная информация

Безопасность

• Используйте HTTPS в продакшене
• Настройте правильные CORS политики
• Не передавайте чувствительные данные в URL

Производительность

• Используйте кеширование на стороне клиента
• Учитывайте rate limiting
• Запрашивайте только нужные поля через параметр fields

Поддержка

При возникновении проблем:

1. Проверьте логи: runtime/logs/app.log
2. Убедитесь, что БД доступна
3. Проверьте настройки в .env

Дополнительные ресурсы

• README.md - Общая информация о проекте
• QUICKSTART.md - Быстрый старт за 5 минут
• README_API.md - Подробная API документация
• FULLTEXT_SEARCH.md - Руководство по полнотекстовому поиску
• SETUP_GUIDE.md - Настройка HTTPS, CI/CD, Swagger
• PROJECT_INFO.md - Детали реализации проекта

Changelog

v1.0.0

• ✅ Базовый CRUD для вакансий
• ✅ Полнотекстовый поиск с FULLTEXT индексами (10-100x быстрее)
• ✅ Пагинация и сортировка
• ✅ Кеширование (списки, поиск, отдельные записи)
• ✅ Rate limiting (100 запросов/час)
• ✅ HTTPS поддержка
• ✅ CI/CD (GitHub Actions + GitLab CI)
• ✅ Полная OpenAPI документация
• ✅ Полное покрытие тестами