Зачем это всё
Если вы когда-нибудь работали с API Честного ЗНАКа, то знаете: официальная документация лежит на docs.crpt.ru в виде HTML-страниц или в виде pdf-талмудов на сотни страниц. Открыть, почитать — да, пожалуйста. А кроме этого, как в том меме: нет ни-че-го. И это в то время, когда космические корабли бороздят просторы вселенной во всём мире принято API документировать через OpenAPI/Swagger.
И мне потребовалась документация ЭДО Лайт именно в формате OpenAPI, чтобы удобно дёргать методы в Bruno и не вбивать каждый запрос руками. Так родилась идея конвертации.
Kimi K3 и swarm-режим
Очень кстати вчера вышла модель Kimi K3. Запустил её в swarm-режиме: несколько агентов параллельно обрабатывали эндпоинты, перекрёстно проверяли друг друга, итеративно уточняли схемы. Такой подход дал на удивление чистый результат — полноценную OpenAPI 3.0 спецификацию в YAML. А главное - это скорость, на всё ушло минут 10-15.
От ЭДО Лайт к True API
Спецификацию ЭДО Лайт я выложил в gist на GitHub и рассказал об этом у себя в блоге, и в комментариях один из подписчиков попросил провернуть то же самое с True API.
True API — это основной API ГИС МТ. Штука на порядок сложнее ЭДО Лайт: официальный PDF с документацией содержит более 700 страниц текста. Десятки эндпоинтов — аутентификация через УКЭП, подача сведений, национальный каталог, СУЗ, выгрузки данных и многое другое. Я сначала подумал, что такой объём нейронка не переварит и не стоит даже влезать в это. А потом всё же решился.
Как и ожидалось, процесс был длительным, но спустя примерно два часа на выходе была готовая спецификация для True API.
А далее дело осталось за малым — оформить это в репозиторий GitHub и поделиться с сообществом.
Что внутри репозитория
Структура простая:
openapi/
true-api.yaml — Спецификация True API
edo-light.yaml — Спецификация ЭДО Лайт
bruno/
true-api/ — Bruno-коллекция True API
environments/ — Окружения (песочница/продуктив × API v3/v4)
edo-light/ — Bruno-коллекция ЭДО Лайт
environments/ — Окружения (продуктив/интеграция)
Каждая Bruno-коллекция разбита по папкам в соответствии с разделами API: Аутентификация, Подача сведений, Квитанции, Выгрузки данных, Национальный каталог, ЭДО Лайт (внутри True API) и так далее. Окружения настроены — выбирай песочницу или продуктив, и вперёд.
Всего 162 файла, покрывающих оба API.
Как пользоваться
- Swagger Editor / Redoc — открыть `.yaml` из папки `openapi/` и изучать/тестировать эндпоинты с удобной визуализацией схем
- Bruno — открыть коллекцию из `bruno/`, выбрать окружение в выпадающем списке, настроить токен в `opencollection.yml`
- OpenAPI Generator — сгенерировать клиент на любом языке. Ну, почти на любом. Кроме 1С...
Отказ от ответственности
Данный проект не является официальным продуктом ООО «Центр развития перспективных технологий» или ООО «Оператор-ЦРПТ». Спецификации и коллекции подготовлены на основе общедоступной документации и не гарантируют полноту, точность или актуальность. Используйте на свой страх и риск. Для получения официальной информации обращайтесь к первоисточнику.
Если нашли неточность или недостающий эндпоинт — пишите issue, а ещё лучше pull request. Репозиторий открыт для сообщества.
Заключение
AI-инструменты кратно ускоряют рутинные задачи, и документирование API — отличный тому пример. То, на что вручную ушли бы недели, Kimi K3 делает за часы.
Этот проект — не замена официальной документации, а дополнение к ней. Мостик между сухими HTML-страницами по ГОСТ и реальными инструментами разработчика: Bruno, Postman, OpenAPI Generator, swagger-интерфейсами.
Если материал оказался полезным — ставьте звёзды репозиторию и делитесь с коллегами.
Вступайте в нашу телеграмм-группу Инфостарт