Bitrixapigen ❤️ ContractFirst

⚙️ Установка

composer require webpractik/bitrixapigen --dev

🔧 Настройка роутинга Bitrix D7

Шаг 1: Настройте роутинг по документации

Шаг 2: local/routes/api.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-контракту

/api/user/register/:
 post:
 tags:
 - User
 summary: User registration
 description: Регистрация пользователя
 operationId: userRegistration
 requestBody:
 description: Обязательные поля
 required: true
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/UserRegisterFields'
 responses:
 '200':
 description: OK
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/UserRegisterResponse'

/api/user/register/:
 post:
 tags:
 - User
 summary: User registration
 description: Регистрация пользователя
 operationId: userRegistration
 requestBody:
 description: Обязательные поля
 required: true
 content:
 application/json:
 schema:
 type: object
 properties:
 EMAIL:
 type: string
 PASSWORD:
 type: string
 responses:
 '200':
 description: OK
 content:
 application/json:
 schema:
 type: object
 properties:
 ID:
 type: number
 example: 111

/api/user/createWithList:
 post:
 tags:
 - User
 summary: Creates list of users with given input array
 description: Creates list of users with given input array
 operationId: createUsersWithListInput
 requestBody:
 content:
 application/json:
 schema:
 type: array
 minItems: 5
 items:
 $ref: '#/components/schemas/User'

/api/user/{userId}/uploadImage:
 post:
 tags:
 - User
 summary: uploads an image
 description: ''
 operationId: uploadFile
 parameters:
 - name: userId
 in: path
 description: ID of user to update
 required: true
 schema:
 type: integer
 format: int64
 - name: additionalMetadata
 in: query
 description: Additional Metadata
 required: false
 schema:
 type: string
 requestBody:
 content:
 application/octet-stream:
 schema:
 type: string
 format: binary

📁 Структура сгенерированного модуля

local/modules/webpractik.bitrixgen/
├── lib/
│ ├── Controllers/
│ ├── Dto/
│ │ └── Collection/
│ ├── Exception/
│ ├── Interfaces/ ← интерфейсы, которые имплементируются в UseCase-классах (один роут - один интерфейс)
│ ├── Response/
│ └── UseCase/ ← UseCase-классы (один роут - один интерфейс - UseCase класс)
├── .settings.php ← регистрация сервисов в DI Bitrix
├── include.php ← точка подключения модуля
├── routes.php ← кастомный файл с роутами

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

$useCase = \Bitrix\Main\DI\ServiceLocator::getInstance()->get('webpractik.bitrixgen.uploadPetFormWithFiles');
return new \Bitrix\Main\Engine\Response\Json(
 $useCase->process($petId, $dto)
);

🧩 Как реализовать функционал роутов

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();
 }
}

<?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]];

\Bitrix\Main\Loader::includeModule('my.module');
\Bitrix\Main\Loader::includeModule('webpractik.bitrixgen'); // строго в конце!

📥 Что передаёт контроллер в UseCase

✅ Валидация

{
 "message": "Валидация не пройдена",
 "errors": [
 {
 "field": "[1][username]",
 "message": "Это поле отсутствует."
 }
 ]
}

🛠 Требования

Roadmap