Документування 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 годин.

Як автоматизу генерацію специфікації на Бітрікс?

Ручне написання 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С-Бітрікс для проєктів будь-якої складності: від архітектурних схем до покрокових інструкцій для контент-менеджера.

Наявність документації скорочує час адаптації нового розробника втричі — з трьох тижнів до одного. Проєкт без неї вимагає в 3 рази більше часу на введення новачка; даунтайми при оновленні ядра трапляються на 60% частіше. Понад 10 років досвіду розробки на Бітрікс і 50+ задокументованих проєктів — це наш стандарт. Економія на онбордингу одного розробника може сягати 90 000 грн — саме стільки коштує місяць простою без документації. Зв’яжіться з нами для оцінки вашого проєкту за один день.

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

Конкретні ситуації, які бачимо на кожному другому проєкті:

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

Статистика наших проєктів: при наявності повної документації кількість інцидентів при оновленні модулів знижується на 50%, а середній час виправлення помилки в продакшні скорочується вдвічі.

Один із кейсів — інтернет-магазин з 500 000 товарів, обмін з 1С, три платіжні системи, інтеграція з СДЕК. Без документації новий розробник розбирався 4 тижні. Ми задокументували архітектуру даних (інфоблоки, HR-блоки, кастомні таблиці), REST API, регламенти деплою та бекапів. Після цього введення новачка зайняло 1 тиждень, а вартість підтримки зменшилася на 35% за рахунок зниження часу на налагодження. За стандартом CommerceML (описано у Вікіпедії) обмін з 1С — одна з найчастіших точок збою. Документація знімає цю проблему.

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

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

Для розробників і 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 та 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С / гальмує
• Контактні особи та зони відповідальності
• Шаблони дій для кожного типу

Як відбувається створення документації?

1. Аналіз проєкту (1–2 дні) — вивчаємо код, БД, конфігурації, спілкуємося з командою.
2. Збір інформації (2–5 днів) — фіксуємо архітектуру, інтеграції, бізнес-процеси.
3. Написання та валідація — формуємо технічну документацію, інструкції, схеми. Кожен текст перевіряє розробник, який брав участь у проєкті.
4. Розміщення — Confluence, GitBook, Notion або Wiki з розмежуванням доступу.
5. Гарантія актуальності — оновлюємо документацію при кожній значущій зміні (новий модуль, зміна обміну, оновлення ядра).

Створення документації 1С-Бітрікс за цим алгоритмом забезпечує точність і повноту — жоден кастомний агент або змінений файл ядра не залишиться незадокументованим. Замовте попередню оцінку документації — ми проаналізуємо ваш проєкт і назвемо строки та обсяг робіт.

Що входить в роботу

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

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

Джерело: власна методологія, апробована на 50+ проєктах на 1С-Бітрікс.

Строки

Замовте документацію під ключ — зв’яжіться з нами для безкоштовної оцінки вашого проєкту за 1 день. Застаріла документація гірша за її відсутність: вона створює хибну впевненість. Ми оновлюємо матеріали при кожній суттєвій зміні, щоб інформація залишалася точною. Отримайте консультацію прямо зараз.