Bitrix24 Apps & BITRIX24-PHP-SDK: “Задача Есть REST-API на 1000+ методов, требуется: 1. отслеживать, каки…”

Задача
Есть REST-API на 1000+ методов, требуется:
1. отслеживать, какие методы SDK поддерживает и какой % покрытия
2. генерировать документацию для разработчиков
3. давать структурированный JSON для возможной кодогенерации силами LLM (планы)

Решение
Нам помогут атрибуты – https://www.php.net/manual/en/language.attributes.php
Вешаем на каждый метод кастомный атрибут ApiEndpointMetadata:


#[ApiEndpointMetadata(
    'crm.contact.add',
    'https://training.bitrix24.com/rest_help/crm/contacts/crm_contact_add.php',
    'Creates a new contact.'
)]
public function add(array $fields, array $params = ['REGISTER_SONET_EVENT' => 'N']): AddedItemResult
{
    return new AddedItemResult(
        $this->core->call(
            'crm.contact.add',
            [
                'fields' => $fields,
                'params' => $params,
            ]
        )
    );
}

И получаем возможность их распарсить и собрать из них документацию.
В части методов используются генераторы, поэтому там есть проблема с выводом правильного типа возвращаемого результата. Её мы решаем конечно же за счёт использования typhoon-php


 * @return Generator<int, ContactItemResult> <==== ПРАВИЛЬНЫЙ ТИП    
 * @throws BaseException
 */
#[ApiBatchMethodMetadata(
    'crm.contact.list',
    'https://training.bitrix24.com/rest_help/crm/contacts/crm_contact_list.php',
    'Returns in batch mode a list of contacts'
)]
public function list(array $order, array $filter, array $select, ?int $limit = null): Generator <==== общий тип Generator
{
    $this->log->debug(
        'list',
        [
            'order' => $order,
            'filter' => $filter,
            'select' => $select,
            'limit' => $limit,
        ]
    );
    foreach ($this->batch->getTraversableList('crm.contact.list', $order, $filter, $select, $limit) as $key => $value) {
        yield $key => new ContactItemResult($value);
    }
}

Что в итоге
1. Все методы аннотированы и генерируется документация
2. Видим % покрытия методов и можем планировать работы и цели по улучшению покрытия

Bitrix24 API-methods count: 1131
Supported in bitrix24-php-sdk methods count: 160
Coverage percentage: 14.15% 🚀