webpractik / bitrixapigen
Requires
- jane-php/open-api-3: ^7.8
- jane-php/open-api-runtime: ^7.8
- nikic/php-parser: ^5.3
- nyholm/psr7: ^1.8
README
Bitrixapigen — пакет для генерации серверной части приложения (контроллеры + дто + роутер) на основе OpenApi контракта на битриксе.
⚙️ Установка
composer require webpractik/bitrixapigen --dev
🔧 Настройка роутинга Bitrix D7
Если на проекте еще настроен роутинг, то сделайте это.
Шаг 1: Настройте роутинг по документации
▶️ Официальная документация Bitrix:
https://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=43&CHAPTER_ID=013764
Шаг 2: local/routes/api.php
Обратите внимание на подключение файлов routes.php. Это кастомный файл, который будет присутствовать в модуле сгенерированном пакетом, поэтому нужно реализовать подключение роутов из routes.php.
<?php use Bitrix\Main\ModuleManager; use Bitrix\Main\Routing\RoutingConfigurator; require_once $_SERVER['DOCUMENT_ROOT'] . '/../vendor/autoload.php'; $getRoutePaths = static function (): array { foreach (ModuleManager::getInstalledModules() as $module) { $route = $_SERVER['DOCUMENT_ROOT'] . '/local/modules/' . $module['ID'] . '/routes.php'; if (file_exists($route)) { $routes[] = $route; } } return $routes ?? []; }; return static function (RoutingConfigurator $configurator) use ($getRoutePaths) { foreach ($getRoutePaths() as $route) { $callback = include $route; if ($callback instanceof Closure) { $callback($configurator); } } };
Шаг 3: Проверьте, что файл local/routes/api.php
подключен в .settings.php
'routing' => [ 'value' => [ 'config' => [ 'api.php', ], ], ],
🚀 Быстрый старт
- Подготовьте OpenAPI-спецификацию (JSON или YAML)
📝 Все данные передаваемые в телах запросов должны быть описаны через схемы (
schema
) в OpenAPI-спецификации. Именно на их основе происходит генерация соответствующих DTO, коллекций и корректная передача аргументов в UseCase.
- Выполните генерацию:
php vendor/bin/bitrixapigen generate --openapi-file path/to/openapi.yaml
или кратко:
php vendor/bin/bitrixapigen generate -o path/to/openapi.yaml
🟡 Параметр --openapi-file (или -o) — обязателен
- Установите модуль:
- через административную панель Bitrix (
/bitrix/admin/partner_modules.php
) - или через миграцию/скрипт
- через административную панель Bitrix (
📁 Структура сгенерированного модуля
⚠️ После генерации необходимо обязательно подключить модуль
webpractik.bitrixgen
в самом конце файлаlocal/php_interface/init.php
, чтобы он корректно зарегистрировал свои контроллеры и роуты.
local/modules/webpractik.bitrixgen/
├── lib/
│ ├── Controllers/
│ ├── Dto/
│ │ └── Collection/
│ ├── Exception/
│ ├── Interfaces/ ← интерфейсы, которые имплементируются в UseCase-классах (один роут - один интерфейс)
│ ├── Response/
│ └── UseCase/ ← UseCase-классы (один роут - один интерфейс - UseCase класс)
├── .settings.php ← регистрация сервисов в DI Bitrix
├── include.php ← точка подключения модуля
├── routes.php ← кастомный файл с роутами
🧠 Архитектура
Для каждого роута генерируется интерфейс, например, Interfaces/IUploadPetFormWithFiles.php
и
класс-заглушка UseCase/UploadPetFormWithFiles.php
, который реализует интерфейс IUploadPetFormWithFiles
.
В файле .settings.php
UploadPetFormWithFiles регистрируется как реализация для интерфейса.
Контроллеры получают входные данные, инициализируют DTO, коллекции или другие переменные и вызывают реализацию интерфейса UseCase через ServiceLocator
:
$useCase = \Bitrix\Main\DI\ServiceLocator::getInstance()->get('webpractik.bitrixgen.uploadPetFormWithFiles'); return new \Bitrix\Main\Engine\Response\Json( $useCase->process($petId, $dto) );
Модуль webpractik.bitrixgen
не должен редактироваться вручную. Любые правки в нем будут утеряны после перегенерации этого модуля.
🧩 Как реализовать функционал роутов
Предполагается, что вся логика роута будет размещена в соответствующем UseCase.
-
Создайте свой модуль, например, my.module
-
Создайте в нем реализацию интерфейса соответствующего роута:
namespace My\Module\UseCase; use Webpractik\Bitrixgen\Interfaces\IUploadPetFormWithFiles; class UploadPetFormWithFiles implements IUploadPetFormWithFiles { public function process(int $petId, \Webpractik\Bitrixgen\Dto\PetFormUpload $dto): ?\Webpractik\Bitrixgen\Dto\Pet { return new \Webpractik\Bitrixgen\Dto\Pet(); } }
- Зарегистрируйте реализацию в
.settings.php
модуляmy.module
:
<?php namespace My\Module; use Bitrix\Main\DI\ServiceLocator; $serviceLocator = ServiceLocator::getInstance(); $serviceValue = []; if ($serviceLocator->has('webpractik.bitrixgen.uploadPetFormWithFiles')) { if (!in_array(\Webpractik\Bitrixgen\Interfaces\IUploadPetFormWithFiles::class, class_implements($serviceLocator->get('webpractik.bitrixgen.uploadPetFormWithFiles')))) { $serviceValue['webpractik.bitrixgen.uploadPetFormWithFiles'] = [\My\Module\UseCase\UploadPetFormWithFiles::class]; } } if (!$serviceLocator->has('webpractik.bitrixgen.uploadPetFormWithFiles')) { $serviceValue['webpractik.bitrixgen.uploadPetFormWithFiles'] = ['className' => \My\Module\UseCase\UploadPetFormWithFiles::class]; } return ['services' => ['value' => $serviceValue]];
- Подключите свой модуль
my.module
в файлеlocal/php_interface/init.php
перед подключением модуляwebpractik.bitrixgen
:
\Bitrix\Main\Loader::includeModule('my.module'); \Bitrix\Main\Loader::includeModule('webpractik.bitrixgen'); // строго в конце!
📥 Что передаёт контроллер в UseCase
Контроллер автоматически передаёт в метод process()
:
$dto
или$collection
— еслиrequestBody
с типомapplication/json
илиmultipart/form-data
string $octetStreamRawContent
— если типrequestBody
—application/octet-stream
array $queryParameters
— если в OpenAPI-спецификации заданы query-параметры- path-параметры — передаются как отдельные переменные (например,
int $petId
)
📤 Формат ответа: JSON и Bitrix-структура
По умолчанию роуты возвращают "чистый" JSON без обёртки Bitrix.
Чтобы включить формат Bitrix, в OpenAPI-документации у роута нужно задать флаг:
x-bitrix-format: true
Пример
/pet/findByStatus: get: x-bitrix-format: true tags: - pet
Поведение:
- Без флага:
{ "id": 123, "name": "doggie" }
- С
x-bitrix-format: true
:
{ "status": "success", "data": { "id": 123, "name": "doggie" } }
Ошибки также будут обёрнуты в формат Bitrix.
🛠 Требования
- PHP 8.1+
- Bitrix Framework (D7)
- OpenAPI 3.0+
Roadmap
- Генерация валидаций
- Генерация ошибок и логика их обработки в контроллере=
- Генерация тестов
- Авторизация в роутах