Danil Iarosh 674e470272 Update API documentation and fix warnings

2026-01-12 17:02:53 +03:00

8.1 KiB

Raw Permalink Blame History

📚 Corp API - Справочник по всем эндпоинтам

🎯 Обзор

Базовый URL: https://corp.robotail.pro/api/v1/
Обнаружено эндпоинтов: 13 (+ корневой)
Тесты: ✅ 22/22 прошли успешно

🔐 Аутентификация

Все эндпоинты требуют Bearer token:

Authorization: Bearer <access_token>

Получение токена:

URL: https://corp.robotail.pro/api/auth/token/
Метод: POST
Тело: {"email": "...", "password": "..."}

📋 Список всех эндпоинтов

1. 🏠 Корневой эндпоинт

GET /api/v1/

Возвращает: Словарь со всеми доступными эндпоинтами
Формат ответа: {"endpoint_name": "full_url", ...}
Тест: ✅ Пройден

2. 📅 События календаря

GET /api/v1/calendar/events/
POST /api/v1/calendar/events/

Возвращает: Массив событий
Методы: GET, POST, HEAD, OPTIONS
Тест: ✅ Пройден

Пример использования:

response = requests.get(
    "https://corp.robotail.pro/api/v1/calendar/events/",
    headers={"Authorization": f"Bearer {token}"}
)
events = response.json()  # list

3. 👥 Сотрудники

GET /api/v1/employees/
POST /api/v1/employees/

Возвращает: Пагинированный список сотрудников
Поля ответа: count, next, previous, results
Методы: GET, POST, HEAD, OPTIONS
Тесты: ✅ 2 теста пройдены

Структура ответа:

{
  "count": 100,
  "next": "https://...?page=2",
  "previous": null,
  "results": [...]
}

4. 🏢 Отделы

GET /api/v1/departments/
POST /api/v1/departments/

Возвращает: Пагинированный список отделов
Поля ответа: count, next, previous, results
Методы: GET, POST, HEAD, OPTIONS
Тест: ✅ Пройден

5. 💼 Должности

GET /api/v1/positions/
POST /api/v1/positions/

Возвращает: Массив должностей
Поля объекта: id, name, description, groups, groups_verbose
Методы: GET, POST, HEAD, OPTIONS
Тест: ✅ Пройден

6. 🎓 Навыки

GET /api/v1/skills/
POST /api/v1/skills/

Возвращает: Массив навыков
Поля объекта: id, name
Методы: GET, POST, HEAD, OPTIONS
Тест: ✅ Пройден

Пример:

[
  {"id": 1, "name": "Python"},
  {"id": 2, "name": "JavaScript"}
]

7. 📝 Действия сотрудников

GET /api/v1/employee-actions/
POST /api/v1/employee-actions/

Возвращает: Массив действий
Поля: id, employee, comment, extra, history, action_display, date, action, date_display
Методы: GET, POST, HEAD, OPTIONS
Тест: ✅ Пройден

8. 📄 Документы

GET /api/v1/documents/
POST /api/v1/documents/

Возвращает: Пагинированный список документов
Поля ответа: count, next, previous, results
Методы: GET, POST, HEAD, OPTIONS
Тест: ✅ Пройден

9. 📨 Запросы

GET /api/v1/requests/
POST /api/v1/requests/

Возвращает: Пагинированный список запросов
Поля ответа: count, next, previous, results
Методы: GET, POST, HEAD, OPTIONS
Тест: ✅ Пройден

10. 📰 Посты

GET /api/v1/posts/
POST /api/v1/posts/

Возвращает: Пагинированный список постов
Поля ответа: count, next, previous, results
Методы: GET, POST, HEAD, OPTIONS
Тест: ✅ Пройден

11. 💬 Комментарии

GET /api/v1/comments/
POST /api/v1/comments/

Возвращает: Пагинированный список комментариев
Поля ответа: count, next, previous, results
Методы: GET, POST, HEAD, OPTIONS
Тест: ✅ Пройден

12. 🎭 Роли отделов

GET /api/v1/department-roles/
POST /api/v1/department-roles/

Возвращает: Пагинированный список ролей
Поля ответа: count, next, previous, results
Методы: GET, POST, HEAD, OPTIONS
Тест: ✅ Пройден

13. 🚫 Группы (ограничен доступ)

GET /api/v1/groups/

Статус: 403 Forbidden
Описание: Доступ ограничен для текущего пользователя
Тест: ✅ Пройден (проверка 403)

🧪 Результаты тестирования

Все тесты (22 из 22): ✅

Функциональные тесты:

✅ Корневой эндпоинт возвращает список
✅ Корневой эндпоинт содержит основные эндпоинты
✅ Calendar events
✅ Employees (список)
✅ Employees (пагинация)
✅ Departments
✅ Positions
✅ Skills
✅ Employee actions
✅ Documents
✅ Requests
✅ Posts
✅ Comments
✅ Department roles
✅ Groups (403)

Тесты безопасности (7):

✅ Employees требует авторизации
✅ Departments требует авторизации
✅ Positions требует авторизации
✅ Documents требует авторизации
✅ Requests требует авторизации
✅ Posts требует авторизации
✅ Comments требует авторизации

📦 Созданные файлы

Файл	Описание	Статус
`requests_corp_api_test.py`	Базовый скрипт для получения токена	✅
`explore_api_endpoints.py`	Рекурсивное обнаружение эндпоинтов	✅
`endpoints_list.py`	Структурированный список эндпоинтов	✅
`test_corp_api.py`	Тесты аутентификации (9 тестов)	✅
`test_all_endpoints.py`	Полный набор тестов (22 теста)	✅
`API_DOCUMENTATION.md`	Документация по аутентификации	✅
`ENDPOINTS_REFERENCE.md`	Этот справочник	✅

🚀 Быстрый старт

1. Получение токена

from requests_corp_api_test import get_token

token = get_token("your@email.com", "password")

2. Использование эндпоинтов

import requests
from endpoints_list import API_BASE_URL

headers = {"Authorization": f"Bearer {token}"}

# Получить список сотрудников
response = requests.get(API_BASE_URL + "employees/", headers=headers)
employees = response.json()

# Получить навыки
response = requests.get(API_BASE_URL + "skills/", headers=headers)
skills = response.json()

3. Запуск тестов

# Все тесты
pytest test_all_endpoints.py -v

# Конкретный класс
pytest test_all_endpoints.py::TestEmployeesEndpoints -v

# С подробным выводом
pytest test_all_endpoints.py -v --tb=short

📊 Статистика

Всего эндпоинтов: 13
Тестов написано: 22
Успешных тестов: 22 (100%)
Время выполнения: ~26 секунд
Пагинированных эндпоинтов: 8
Array эндпоинтов: 4
Ограниченных эндпоинтов: 1 (groups)

8.1 KiB Raw Permalink Blame History Unescape Escape