Документирование API 1С-Битрикс: OpenAPI и Swagger UI

Клиент потратил месяц на интеграцию с платёжным шлюзом: документация 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 на сайте Битрикс

1. Скачать дистрибутив Swagger UI (папка dist/).
2. Расположить в /local/swagger/.
3. Создать файл спецификации /local/swagger/openapi.yaml.
4. Настроить роутинг: страница /api/docs отдаёт HTML Swagger UI.
5. Закрыть доступ через .htaccess или middleware для неавторизованных пользователей.

Пример .htaccess для защиты:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule ^local/swagger/ - [F]
</IfModule>

Сравнение подходов

Процесс работы и типовые сроки

Все цифры — ориентировочные, зависят от сложности 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.

Документация проектов на 1С-Битрикс

Разработчик уволился. Новый открывает init.php на 2000 строк — видит 47 обработчиков событий через AddEventHandler, цепочку агентов в b_agent и кастомный модуль без единого комментария. На вникание уходит месяц. Документация этот месяц превращает в три дня. Мы создаём её для проектов на 1С-Битрикс: от архитектурных схем до пошаговых инструкций для контент-менеджера.

Наличие документации сокращает время адаптации нового разработчика в три раза — с трёх недель до одной. Без неё каждый второй проект сталкивается с даунтаймом при обновлении ядра или сбоях обмена с 1С. Более 10 лет опыта разработки на Битрикс и 50+ задокументированных проектов — это наш стандарт. Получите консультацию по вашему проекту: мы оценим объём работ за один день.

Почему документация критична?

Конкретные ситуации, которые видим на каждом втором проекте:

• Обновление ядра — разработчик запускает bitrix/tools/upgrade.php. Обновление перезаписывает модифицированные файлы в /bitrix/components/bitrix/. Никто не знает, какие компоненты были изменены. Сайт сломался. Откат — из бекапа. Даунтайм — 4 часа.
• Обмен с 1С — агент обмена CCatalogImport::PreGenerateXML падает с ошибкой. Настройка нестандартна. Кто менял маппинг свойств? Без документации — реверс-инжиниринг на полдня.
• Новый подрядчик — команда получает проект с 12 highload-блоками без описания назначения, кастомными таблицами b_custom_order_log и b_product_sync_history. Назначение и связи с инфоблоками нигде не зафиксированы. Это затягивает ввод нового разработчика на две недели.
• Рост команды — каждый новый разработчик три недели ходит за «тем, кто знает», вместо того чтобы открыть документацию и работать.

Как структурировать документацию для разработчиков?

Техническая документация

Для разработчиков и DevOps — внутреннее устройство проекта:

Архитектура:

• Используемые модули Битрикс (sale, catalog, iblock, main, кастомные)
• Путь запроса: HTTP → nginx → urlrewrite.php → компонент → шаблон → ответ
• Серверная инфраструктура: конфигурация, топология, балансировка

Структура данных — самая критичная часть:

• Инфоблоки: типы (IBlock::TYPE_ID), разделы, свойства (PROPERTY_CODE), связи между инфоблоками через свойство типа «Привязка к элементам»
• Highload-блоки: таблица b_hlblock_entity, назначение каждого блока, структура полей, пользовательские поля (UF_*), индексы
• Кастомные таблицы в БД — зачем создавались, DDL, связи с b_iblock_element, b_sale_order и другими штатными таблицами
• Торговый каталог: типы цен (b_catalog_group), склады (b_catalog_store), правила корзины (b_sale_discount)

Кастомные разработки:

• Компоненты в /local/components/ — назначение, class.php, входные параметры (.parameters.php), шаблоны, зависимости
• Модули в /local/modules/ — API, события, установочные скрипты
• Обработчики событий — список всех AddEventHandler/registerEventHandler с описанием: какое событие, что делает, критичность
• Агенты (b_agent) — расписание, функционал, какие нельзя останавливать (обмен с 1С, рассылки, очистка корзин)
• Изменённые файлы ядра — полный список. При обновлении bitrix/ эти файлы будут перезаписаны

Интеграции:

• Обмен с 1С: настройки модуля catalog → «Обмен с 1С», формат CommerceML, расписание CCatalogImport, маппинг свойств, подводные камни (кодировки, таймауты, размер import.xml)
• Платёжные системы: обработчики в sale.handlers, режимы работы (тест/бой), URL для callback
• Службы доставки: профили в sale.delivery, алгоритмы расчёта, API-ключи
• CRM, маркетплейсы, внешние API: эндпоинты, механизмы аутентификации, частота синхронизации

Пользовательские инструкции

Для контент-менеджеров и администраторов:

Руководство контент-менеджера:

• Управление каталогом: создание элементов инфоблока, заполнение свойств, работа с разделами. Какие поля обязательны, какие влияют на отображение на сайте
• Изображения: допустимые размеры (авторесайз настроен или нет?), форматы, процесс загрузки в DETAIL_PICTURE и PROPERTY_GALLERY
• Акции и скидки — как настроить правило корзины в «Маркетинг» → «Правила работы с корзиной», не сломав ценообразование. Проверка через тестовый заказ

Руководство администратора:

• Пользователи: группы (b_group), права доступа к модулям и инфоблокам
• Обработка заказов: статусы (b_sale_status), оплата, возвраты
• Бекап через «Настройки» → «Резервное копирование» — с оговоркой, что для больших проектов штатный бекап не справляется

Формат:

• Пошагово с нумерацией
• Скриншоты с аннотациями — стрелки, выделения, подписи
• FAQ из реальных вопросов, собранных при обучении
• Видеоинструкции для нетривиальных операций (по запросу)

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

Для проектов с кастомным REST API — мы описываем все эндпоинты: метод, URL, назначение, параметры (обязательные/опциональные), формат ответа. Аутентификация: механизм получения токена, TTL, обновление. Rate limiting: лимиты, HTTP-коды при превышении. Примеры — рабочие cURL-команды, не теоретические. Инструменты: Swagger/OpenAPI (согласно стандарту REST API) и Postman Collection для тестирования.

Архитектурные схемы

Одна схема заменяет 10 страниц текста. Форматы: Draw.io, Mermaid (версионируется в Git), PlantUML.

• Инфраструктура — серверы, сети, балансировщик, БД (master-slave?), Redis, CDN. Физическая и логическая топология
• Компоненты — модули Битрикс, кастомные компоненты в /local/, внешние сервисы, связи
• ER-диаграмма — таблицы b_iblock_element, b_sale_order, highload-блоки, кастомные таблицы. Поля, связи, индексы. Особенно критично для кастомных таблиц, которых нет в документации Битрикс
• Потоки данных — как информация движется между Битрикс, 1С, маркетплейсами, CRM, платёжными системами
• Карта сайта — что инфоблок, что статическая страница, что кастомный раздел на компоненте

Регламенты эксплуатации

Деплой:

• Пошаговая инструкция для staging и production
• Чек-лист после деплоя: проверка главной, каталога, чекаута, обмена с 1С
• Процедура отката — какой symlink переключить, какой бекап БД восстановить

Бекапы:

• Расписание: БД, upload/, конфигурации
• Где хранятся и сколько
• Процедура восстановления — проверенная, не теоретическая
• Тестовое восстановление раз в месяц

Обновление ядра:

• Staging → тестирование → production. Строго в таком порядке
• Проверка совместимости кастомных компонентов и изменённых файлов ядра
• bitrix/updates/ — что было обновлено

Инциденты:

• Классификация: сайт недоступен / ошибки 500 / сломался обмен с 1С / тормозит
• Контактные лица и зоны ответственности
• Шаблоны действий для каждого типа

Что входит в работу

Мы готовим полный комплект документации для вашего проекта:

• Техническая документация с описанием архитектуры, структуры данных, кастомных разработок и интеграций
• Пользовательские инструкции для контент-менеджеров и администраторов
• API-документация в формате Swagger/OpenAPI с Postman-коллекцией
• Архитектурные схемы (инфраструктура, ER-диаграммы, потоки данных)
• Регламенты эксплуатации (деплой, бекапы, обновление ядра, инциденты)
• Размещение в Confluence, GitBook, Notion или Wiki с разграничением доступа
• Гарантия актуальности — обновляем документацию при каждом значимом изменении

Сроки

Закажите документацию под ключ. Свяжитесь с нами — мы оценим ваш проект за один день. Устаревшая документация хуже её отсутствия: она создаёт ложную уверенность. Обновляем при каждом существенном изменении, чтобы информация оставалась точной.