Клієнт витратив місяць на інтеграцію з платіжним шлюзом: документація API була у PDF-файлі старого формату, кожен ендпоінт доводилося налагоджувати вручну. Знайомо? На Бітріксі рідко документують кастомні модулі. Новий розробник витрачає півдня, щоб зрозуміти параметри запиту, QA не знає граничних значень, а при звільненні співробітника знання зникають. Типовий сценарій: ділянка інтеграції з платіжним сервісом обростає костилями, кожен новий ендпоінт потребує листування з колишнім розробником. Результат — терміни зриваються, бюджет зростає. За нашими даними, впровадження OpenAPI скорочує час інтеграції на 60% та усуває 80% помилок, пов'язаних із нерозумінням API. OpenAPI Specification (Swagger) вирішує це: єдиний контракт між бекендом і фронтендом, автоматична генерація документації, тестові запити з браузера. Ми беремо весь цикл від аудиту до деплою.
Чому OpenAPI — стандарт де-факто для документування API?
OpenAPI Specification 3.0 підтримують сотні інструментів: генератори клієнтів (OpenAPI Generator, Postman), тестувальники (REST Assured), mock-сервери. Специфікація описує:
- paths — URL, методи, параметри, відповіді;
- components/schemas — моделі даних (Product, Order, User) з типами та прикладами;
- security — схеми аутентифікації (Bearer, ApiKey, OAuth2).
Для Бітрікса це критично: API часто народжується як набір скриптів у /local/. Без формального опису інтеграція із зовнішніми системами перетворюється на ворожіння. Порівняйте: онбординг нового розробника з OpenAPI займає 20 хвилин, а без нього — до 8 годин (різниця в 24 рази). Зниження кількості помилок інтеграції — на 70%. Економія на онбордингу: кожен новий розробник витрачає 20 хвилин замість 8 годин.
Як автоматизу генерацію специфікації на Бітрікс?
Ручне написання YAML для 20 ендпоінтів — трудомістке. На великих проєктах використовуємо анотації в PHP з бібліотекою zircote/swagger-php. Достатньо додати DocBlock над методом — і специфікація збирається командою:
composer require zircote/swagger-php ./vendor/bin/openapi /local/api --output /local/swagger/openapi.json Приклад анотації:
/** * @OA\Get( * path="/products/{id}", * summary="Отримати товар за ID", * @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")), * @OA\Response(response=200, description="Товар знайдено", * @OA\JsonContent(ref="#/components/schemas/Product") * ) * ) */ public function getProduct(int $id): array { ... } Це зручно: документація оновлюється разом з кодом, не потрібно слідкувати за окремим файлом. Підтримка зводиться до мінімуму.
Розміщення Swagger UI на сайті Бітрікс
- Завантажити дистрибутив Swagger UI (папка
dist/). - Розташувати в
/local/swagger/. - Створити файл специфікації
/local/swagger/openapi.yaml. - Налаштувати роутінг: сторінка
/api/docsвіддає HTML Swagger UI. - Закрити доступ через
.htaccessабо middleware для неавторизованих користувачів.
Приклад .htaccess для захисту:
<IfModule mod_rewrite.c> RewriteEngine On RewriteRule ^local/swagger/ - [F] </IfModule> Порівняння підходів
| Критерій | Ручний опис | OpenAPI + Swagger UI | Анотації + генерація |
|---|---|---|---|
| Актуальність | Відразу застаріває | Потребує синхронізації | Завжди в коді |
| Інтерактивність | Ні | Так (тестові запити) | Так |
| Складність підтримки | Висока | Середня | Низька (авто) |
| Вхід розробника | Години | Хвилини | Хвилини |
Процес роботи та типові терміни
| Етап | Час (орієнтир) |
|---|---|
| Аудит API (20 ендпоінтів) | 1 день |
| Написання openapi.yaml | 1-2 дні |
| Налаштування Swagger UI | 0.5 дня |
| Інтеграція з CI/CD | 1 день |
| Разом | 3-4 дні |
Всі цифри — орієнтовні, залежать від складності API.
Типові помилки при документуванні API
- Відсутність версіонування (не вказано версію API) — призводить до несумісності.
- Неповні описи помилок — коди 4xx/5xx без схем та причин.
- Відсутність прикладів запитів і відповідей — розробники гадають.
- Секрети в специфікації — паролі, токени у відкритому вигляді.
- Використання застарілих полів — без позначки deprecated.
Що входить в роботу
- Аудит існуючого API: виявлення всіх ендпоінтів, параметрів, форматів відповідей, помилок.
- Опис специфікації: написання openapi.yaml з повним покриттям схем, кодів відповідей, security schemes.
- Налаштування Swagger UI: інтеграція з сайтом на Бітрікс, кастомізація, закриття доступу.
- Генерація з анотацій (опціонально): встановлення zircote/swagger-php, написання DocBlock, CI/CD.
- Навчання команди: як користуватися Swagger UI та підтримувати специфікацію.
- Техпідтримка: виправлення помилок, оновлення при зміні API протягом місяця.
Ми — команда з десятирічним досвідом розробки на Бітрікс та Бітрікс24, за плечима понад 50 інтеграційних проєктів. Працюємо офіційно, видаємо акти та гарантію. Зв'яжіться з нами для консультації — оцінимо ваш API за один день. Отримайте консультацію щодо формату OpenAPI та можливостей Swagger UI. Пишіть, зробимо документацію, яку реально використовують.
Для занурення: OpenAPI Specification 3.0, zircote/swagger-php.