Запрос функции: OpenAPI для REST API

+1. Тоже ищу это. Есть какие новости?

Спасибо, @mrz — очень полезно. Особенно для практического создания скинов (потому что /webfig/list вроде бы совпадает со значениями, которые идут в файл «skin»). Но до удобного использования в REST-инструментах типа Postman ему ещё далеко… Тем не менее, полезно: файлы, к которым обращается /webfig/list, на самом деле перечисляют все атрибуты, что удобно. Но вывод из файла JG, похоже, использует именно имена из «Webfig» (логично, учитывая контекст), при этом нигде не указано эквивалентное имя для CLI/REST (например, «DHCP Client» vs. «dhcp-client»), так что для преобразования нужно как-то сопоставлять их. Весь этот процесс — большой проект. Если кому-то поможет, я написал небольшой код на JavaScript для парсинга вывода — поскольку /webfig/list не является современным JSON (но похож на формат «webfig skin JSON»), для разбора нужно использовать eval(). Я с этим дальше ничего не делал, но хотя бы можно более удобно смотреть данные. Либо можно собрать такие данные с разных версий, чтобы сравнить изменения схемы от релиза к релизу.

function webfiglist(ip) {
 if (typeof window === "object" && !ip) {
   ip = (new URL(window.location.href)).host
 }
 return new Promise((done) => {
   fetch(`http://${ip}/webfig/list`)
     .then((req) => req.text())
     .then((txt) => {
       var results = {};
       /* это важно...
          /webfig/list — это не валидный JSON, а JS-фрагмент,
          поэтому для преобразования в переменную нужно использовать eval() */
       eval(`results = [${txt}]`);
       done(results);
     });
 });
}

function webfigschemas(ip) {
 if (typeof window === "object" && !ip) {
   ip = (new URL(window.location.href)).host
 }
 return webfiglist(ip).then((list) =>
   Promise.all(
     list
       .filter((i) => i.unique)
       .map((i) => {
         return new Promise((done) => {
           let file = i.name
           fetch(`http://${ip}/webfig/${file}`)
             .then((req) => req.text())
             .then((txt) => {
               /* тот же трюк с eval(), только возвращаем «кортеж» [имя файла, данные] */
               var results
               eval(`results = ${txt}`)
               done([file, results])
             })
         })
       })
   )
 )
}

webfiglist().then(console.log)
webfigschemas().then(console.log)

// NODE.JS сохранение в файл
// let ip = "192.168.88.1"
// const fs = require('fs');
// webfigschemas(ip).then(d => fs.writeFileSync("./webfig-list-schema.json", JSON.stringify(d)))

Если вставить этот код в консоль JavaScript в браузере (включив «Inspect» на странице webfig), то в консоли отобразится «датасхема». Если использовать nodeJS, можно передать ip-адрес в webfiglist("192.168.88.1") и получить данные с любого устройства RouterOS (возможно, это получится сделать и в браузере, но для кросс-доменных запросов понадобится настроить проверки безопасности).

Интересно, есть ли где-нибудь документация по inspect request=child и другим связанным функциям?

Но теперь мы можем их найти. Это не критично для моих задач, но я написал код, который вытягивает все «дочки» (request=child) из /console/inspect. Он использует рекурсию с ROS-функцией для обхода дерева «child» и возвращает ROS::array (и одновременно кладёт результат в глобальную переменную “$ast”). Удивительно, но это НЕ вызывает переполнение стека или превышение лимитов памяти, по крайней мере в версии v7.6.

На самом деле, после обхода дерева, даже на небольшом cAP, находится 4329 уникальных ветвей “cmd”, “args” и “path”, каждая с несколькими листами.

:global ast [:toarray ""]

:global mkast do={
   :global mkast
   :global ast
   :local path ""
   :if ([:typeof $1] ~ "str|array") do={ :set path $1 }
   :local pchild [/console/inspect as-value request=child path=$path]
   :foreach k,v in=$pchild do={
       :if (($v->"type") = "child") do={
           :local astkey ""
           :local arrpath [:toarray $path]
           :foreach part in=$arrpath do={
               :set astkey "$astkey/$part"
           }
           :set ($ast->$astkey->($v->"name")) $v
           :put "Обрабатываю: $astkey $($v->"name") $($v->"node-type")"
           :local newpath "$($path),$($v->"name")"
    # TODO использовать [/console/inspect as-value request=syntax path=$path]
           [$mkast $newpath]
       }
   }
   return $ast
}

# и этот вызов запускает рекурсию
:put [$mkast]

$ast также будет содержать схему в виде вложенного массива, отражающего отношения родитель/дочка… так что можно использовать так: :put ($ast->"/ip/address")

add=.id=*2;name=add;node-type=cmd;type=child;comment=.id=*3;name=comment;node-type=cmd;type=child;disable=.id=*4;name=disable;node-type=cmd;type=child;edit=.id=*5;name=edit;node-type=cmd;type=child;enable=.id=*6;name=enable;node-type=cmd;type=child;export=.id=*7;name=export;node-type=cmd;type=child;find=.id=*8;name=find;node-type=cmd;type=child;get=.id=*9;name=get;node-type=cmd;type=child;print=.id=*a;name=print;node-type=cmd;type=child;remove=.id=*b;name=remove;node-type=cmd;type=child;reset=.id=*c;name=reset;node-type=cmd;type=child;set=.id=*d;name=set;node-type=cmd;type=child

Ещё пример — часть вывода массива $ast выше в виде YAML-подобного формата:

/zerotier/edit:
   number:
     .id: *2
     name: number
     node-type: arg
     type: child
   value-name:
     .id: *3
     name: value-name
     node-type: arg
     type: child
 /zerotier/enable:
   numbers:
     .id: *2
     name: numbers
     node-type: arg
     type: child

Я тут это не делал, но если добавить ещё один вызов “/console/inspect request=syntax …” для каждого child с тем же путём, можно получить описание (например, тип — «объяснение»). Тогда у вас будет вся информация для REST-схемы. Думаю, RAML было бы легче сгенерировать из ROS-скрипта, так как он использует формат YAML, а не JSON, и YAML проще сгенерировать в ROS-скрипте. Мне кажется, ключи из моего кода достаточно близки к REST POST-полям, так что это будет самый простой путь смоделировать в RAML.

И, насколько я знаю, кое-какие инструменты могут использовать или конвертировать схему из RAML в swagger/OpenAPI. Но /console/inspect действительно содержит данные для REST-схемы, хотя конвертация — это всё ещё дополнительная работа.

Единственное замечание: /console/inspect, похоже, знает обо всех пакетах (например, «extra-packages»), даже если они не установлены — так что вы увидите child-записи для calea, iot и прочих, даже если они недоступны.

Сегодня снова пересмотрел это, думал, будет легко получить «объяснение». Хотя «request=child» работает с issue, некоторые «request=syntax» (например, «path=ip,address,add,interface», см. ниже) вызывают полный сбой терминала («Console has crashed; please log in again.») — при этом большинство запросов с request=syntax работают нормально.

[user@router] > /console/inspect request=syntax path=ip,address,add
Колонки: TYPE, SYMBOL, SYMBOL-TYPE, NESTED, NONORM, TEXT  
TYPE    SYMBOL     SYMBOL-TYPE  NESTED  NONORM  TEXT  
syntax             collection        0  yes  
syntax  address    explanation       1  no      Локальный IP-адрес  
syntax  broadcast  explanation       1  no      Широковещательный адрес  
syntax  comment    explanation       1  no      Краткое описание элемента  
syntax  copy-from  explanation       1  no      Номер элемента  
syntax  disabled   explanation       1  no      Определяет, игнорируется элемент или используется  
syntax  interface  explanation       1  no      Имя интерфейса  
syntax  netmask    explanation       1  no      Маска сети  
syntax  network    explanation       1  no      Префикс сети  

[user@router] > /console/inspect request=syntax path=ip,address,add,address
Колонки: TYPE, SYMBOL, SYMBOL-TYPE, NESTED, NONORM, TEXT  
TYPE    SYMBOL   SYMBOL-TYPE  NESTED  NONORM  TEXT  
syntax  Address  definition        0  no      A.B.C.D    (IP-адрес)  

[user@router] > /console/inspect request=syntax path=ip,address,add,interface

Консоль упала; пожалуйста, войдите снова. Даже обернув это в «:do {} on-error={}» сбой не ловится, так что этот способ не сработал.  

:do {  
  /console/inspect request=syntax path=ip,address,add,interface  
} on-error={:put "got error"}  

Хотя для схемы это не было бы критично, там всё же есть описание, которое можно установить, и есть какой-то узел типа «collection», который, вероятно, указывает на возможный массив (а не просто строку) в качестве параметра JSON.  

К слову, тот же /console/inspect можно вызвать и через REST API. Но при тех же параметрах в REST («{ “request”: “syntax”,  “path”: “ip,address,add,interface” }») терминал не падает, а просто виснет без данных (пустой JSON-массив).  

На самом деле, вот RAML для /console/inspect:  
#%RAML 1.0  
title: ROS.RAML sample  
version: 7.6  
protocols: [HTTPS]
mediaType: [application/json]
securitySchemes:  
 basic:  
   description: |  
     Mikrotik REST API поддерживает только Basic Authentication, защищённую HTTPS  
   type: Basic Authentication  
securedBy: [basic]
baseUri: https://{host}:{port}/rest  
baseUriParameters:  
 host:  
   description: IP-адрес или имя хоста устройства RouterOS  
   default: "192.168.88.1"  
 port:  
   description: HTTPS-порт RouterOS  
   default: "443"  
documentation:  
 - title: RouterOS RAML Schema  
   content: |  
     Схема генерируется с помощью `/console/inspect` на устройствах RouterOS и  
     интерпретируется согласно правилам из  
     [Mikrotik REST documentation](https://help.mikrotik.com)  
 - title: Только демо  
   content: Просто пробуем несколько команд  

/console:  
 /inspect:  
   post:  
     description: Инспекция AST RouterOS  
     body:  
       application/json:  
         type: object  
         properties:  
           .proplist?:  
             type: string  
             description: Список свойств для возврата (смотрите документы RouterOS)  
           .query?:  
             type: string  
             description: Список свойств для возврата (смотрите документы RouterOS)  
           path?:  
             type: string  
             description: Строка путей RouterOS, разделённых запятыми  
             example:  
           input?:  
             type: string  
           request:  
             type: string  
             enum: [self|child|completion|highlight|syntax|error]
         example:  
             path: "ip,address,add,interface"  
             request: syntax  
     responses:  
       200:  
         body:  
           application/json:  
             type: array

Вот схема OpenAPI, которую я сгенерировал на основе приведённой выше RAML-схемы. Схема OpenAPI 3.0 / swagger https://tikoci.github.io/restraml/routeros-openapi3.json Возможно, в ней есть вызовы, которые не допускаются, и кое-что могло перевестись не идеально. Но она загружается:

Недавно я автоматизировал создание файлов схем на GitHub, включая OpenAPI 2.0 (OAS2). Так что более новые (и старые) версии схем RAML и OpenAPI доступны по адресу: https://tikoci.github.io/restraml. На той же странице есть удобный инструмент для сравнения (diff), чтобы увидеть изменения между версиями RouterOS. Теперь проще отслеживать изменения между версиями…