Клиент потратил месяц на интеграцию с платёжным шлюзом: документация 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 часов, что при средней ставке 2 000 руб./час даёт экономию до 40 000 руб. в месяц.
Как автоматизировать генерацию спецификации на Битрикс?
Ручное написание 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 день | от 10 000 до 15 000 руб. |
| Написание openapi.yaml | 1-2 дня | от 15 000 до 30 000 руб. |
| Настройка Swagger UI | 0.5 дня | от 5 000 до 10 000 руб. |
| Интеграция с CI/CD | 1 день | от 10 000 до 15 000 руб. |
| Итого | 3-4 дня | от 40 000 до 70 000 руб. |
Все цифры — ориентировочные, зависят от сложности 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.