Documentation as Code: как мы создали новую версию документации для Rest API

info@vsetut.pro

О проекте

Вернуться

01.11.2024 17:04:27 | Хабр

Хабы: Блог компании Битрикс24, Open source, Подготовка технической документации

Привет! Меня зовут Сергей Востриков, я руковожу направлением Маркет и интеграций в Битрикс. Иными словами, я помогаю развивать функционал Битрикс24, доступный для разработчиков тиражных решений и индивидуальных кастомизаций. Это значит REST API и всё «вокруг» него — документацию, витрину Битрикс24 Маркет, кабинет разработчика решений и т.д.

REST API Битрикс24 включает в себя просто страшно сказать сколько методов, событий, встроек виджетов и прочих нюансов. Без документации с этим, конечно, совершенно невозможно иметь дело. И хотя нельзя сказать, что документации у нас не было, надо признать, что с течением времени у разработчиков накопилось к ней немало претензий.

Недавно мы показали сообществу разработчиков нашу новую документацию и, наконец, можем рассказать о том, как появился этот проект, как мы над ним работали и что планируем делать дальше.

Изменения назревали давно — копились проблемы, существующая платформа требовала слишком большого количества ресурсов, вносить материалы через админку в инфоблоки становилось все труднее, не говоря уже о сложностях с автоматизацией процесса при такой «технологии».

Добавлю, что в требования к третьей версии Rest API, которая (спойлер!) сейчас находится в разработке, мы заложили автоматическую генерацию документации из исходного кода продукта, вместо того чтобы продолжать вручную писать таблички с описанием методов.

Однако ждать выхода нового Rest API мы не стали — нам предстояла долгая работа, мы решили подготовиться заранее. Кроме того, текущую версию REST API мы будем поддерживать еще долго, так что хорошая документация для неё всё равно нужна.

Подробнее