Хотя это не «скрипт», у меня есть реализация на JavaScript, которая через /system/console по REST генерирует RAML 1.0 схему. Просто раньше я это здесь не выкладывал, вот теперь делюсь. Это не идеально, скорее около 90%. Например, особенно с аргументами — как и у ChatGPT, может допускать пару ошибок, но в основном всё работает, особенно POST-запросы. В большинстве случаев по типам не придирается — почти все помечены как «any». Есть баги в /console/inspect при использовании request=syntax — некоторые падают, поэтому синтаксических данных мало используется. Есть все пакеты, кроме calea, возврат атрибутов «неточный» — просто отмечен как «any». JSON-аргументы в основном списки (возможно, не всегда), но типы по-прежнему «any». Поскольку схема генерируется автоматически, в ней нет «примеров» или «документации», только эндпоинты и аргументы. GET-запросы не полностью описаны для корневых команд (GET /ip/address) — там должны быть указаны query-параметры и вывод в виде массива. Некоторые настройки по умолчанию для Postman можно улучшить, но не очень понятно, как это контролировать через RAML… Наверняка есть и другие недостатки… В любом случае — хороший старт для более формализованной схемы. Хотя это и не OpenAPI/swagger напрямую, RAML отлично импортируется в Postman.
RAML-схема для скачивания
Сгенерированную RAML-схему для импорта (~6 МБ, 250 тысяч строк YAML) можно скачать по ссылке:
Проверяйте сайт на наличие новых версий. Более свежие версии лежат в GitHub-проекте, но оригинальные файлы по состоянию на момент этого поста остались тут:
7.12 —
7.13 —
Использование Postman… (и других HTTP-инструментов)
Чтобы использовать в Postman:
- Перейдите в секцию API
- Нажмите кнопку «Import» вверху секции API
- Загрузите RAML-файл из вышеуказанных ссылок
- Нажмите «View import setting» и выберите «Schema», а не стандартный «example» в качестве источника для данных запросов/ответов Postman
- Нажмите иконку назад в левом верхнем углу, затем «Import»
- Подождите (Postman показывает прогресс в статус-баре)
- Перейдите в секцию «Collections» слева, увидите новый RouterOS
Работать с Postman дальше — дело пользователя. По крайней мере, нужно добавить:
- «Basic Auth» должен быть настроен либо на коллекцию, либо другой уровень
- {{baseUrl}} надо задать IP вашего роутера через переменные окружения в Postman
Конвертация RAML в OpenAPI/swagger
Этот сайт вроде позволяет взять RAML-схему и получить из неё OpenAPI:
Сгенерированная OpenAPI-схема:
Хотя я мало тестировал, по крайней мере в Postman она загружается. Наверняка есть другие CLI-инструменты для этого, но главное, что Postman поддерживает RAML — это было важно.
JavaScript для генерации RAML
В основном для справки. Генерация занимает около 30 минут и выполняет свыше 30 тысяч REST-запросов на мощном MacBook. Исходники JS доступны в GitHub-проекте:
Код не изящный, но работает. Пока не обернул в контейнер, если времени хватит — займусь позже.
P.S. Можно было написать RouterOS скрипт, но 4К кусков по 6 МБ звучит не очень весело — хотя RSC-скрипт или контейнер теоретически тоже подойдут. JS-шный способ был проще и быстрее, так как большую часть работы я уже сделал раньше.
Postman в VSCode с RouterOS REST…
Использование расширения Postman для VSCode тоже работает, как только схема загружена:
Включая генерацию кода Postman из REST-схемы.
Правки:
- Добавил TODO
- Исправил ссылки, чтобы использовать GitHub-проект вместо гита для скачивания RAML-схемы
- Добавил скриншот VSCode с плагином Postman
- Обновил URL для генерации OpenAPI схемы
- Обновил ссылки на GitHub-проект.
RAML-схема для скачивания
Сгенерированную RAML-схему для импорта (~6 МБ, 250 тысяч строк YAML) можно скачать по ссылке:
Проверяйте сайт на наличие новых версий. Более свежие версии лежат в GitHub-проекте, но оригинальные файлы по состоянию на момент этого поста остались тут:
7.12 —
7.13 —
Использование Postman… (и других HTTP-инструментов)
Чтобы использовать в Postman:
- Перейдите в секцию API
- Нажмите кнопку «Import» вверху секции API
- Загрузите RAML-файл из вышеуказанных ссылок
- Нажмите «View import setting» и выберите «Schema», а не стандартный «example» в качестве источника для данных запросов/ответов Postman
- Нажмите иконку назад в левом верхнем углу, затем «Import»
- Подождите (Postman показывает прогресс в статус-баре)
- Перейдите в секцию «Collections» слева, увидите новый RouterOS
Работать с Postman дальше — дело пользователя. По крайней мере, нужно добавить:
- «Basic Auth» должен быть настроен либо на коллекцию, либо другой уровень
- {{baseUrl}} надо задать IP вашего роутера через переменные окружения в Postman
Конвертация RAML в OpenAPI/swagger
Этот сайт вроде позволяет взять RAML-схему и получить из неё OpenAPI:
Сгенерированная OpenAPI-схема:
Хотя я мало тестировал, по крайней мере в Postman она загружается. Наверняка есть другие CLI-инструменты для этого, но главное, что Postman поддерживает RAML — это было важно.
JavaScript для генерации RAML
В основном для справки. Генерация занимает около 30 минут и выполняет свыше 30 тысяч REST-запросов на мощном MacBook. Исходники JS доступны в GitHub-проекте:
Код не изящный, но работает. Пока не обернул в контейнер, если времени хватит — займусь позже.
P.S. Можно было написать RouterOS скрипт, но 4К кусков по 6 МБ звучит не очень весело — хотя RSC-скрипт или контейнер теоретически тоже подойдут. JS-шный способ был проще и быстрее, так как большую часть работы я уже сделал раньше.
Postman в VSCode с RouterOS REST…
Использование расширения Postman для VSCode тоже работает, как только схема загружена:
Включая генерацию кода Postman из REST-схемы.
Правки:
- Добавил TODO
- Исправил ссылки, чтобы использовать GitHub-проект вместо гита для скачивания RAML-схемы
- Добавил скриншот VSCode с плагином Postman
- Обновил URL для генерации OpenAPI схемы
- Обновил ссылки на GitHub-проект.
