MikroTik

While not "scripting", I had a JavaScript implementation that using /system/console via REST to generate a RAML 1.0 scheme. I just hadn't written it up here, so here it is.

It isn't exactly 100%, perhaps 90%. e.g.
- especially the arguments – and like ChatGPT – it may make a few — but most should work, especially POST ones.
- in most cases, it it's NOT picky on types – most are marked an "any".
- there BUGS in /console/inspect using request=syntax – some crash so not a lot of "syntax" data is used
- has all packages, except calea
- return attributes are "inexact" – it just marked as "any" JSON
- arguments are generally list (perhaps not in all cases), but again types are "any"
- since it's automatically generated, there are no "examples" or "documentation" in schema – just endpoints and args
- GET is not fully specified for root commands (GET /ip/address) – it should show query params and array output
- some postman-defaults could be better, but unsure how to control via RAML...
- likely others...

Anyway still good start to a more formalized schema. While not directly OpenAPI/swagger, the RAML imports into postman just fine.


RAML Schema for Download
The generated RAML schema for import (~6MB, 250K lines of YAML) can be download from:
https://tikoci.github.io/restraml
Check the website for new ones.


Newer version are on the GitHub project but orginal files from time of this posting remain:
7.12 - https://tikoci.github.io/restraml/routeros.raml
7.13 - https://tikoci.github.io/restraml/routeros.7.13.raml


Using Postman... (and other HTTP tools)



For use in Postman
1. Go to API section
2. Click "Import" button on near top of API section
3. Upload the RAML file from above:

4. Click "View import setting", selecting "Schema" – NOT the default "example" — as source for postman request/response data:

5. Hit back icon in upper left, then click "Import"
6. Wait... (postman shows progress in status bar)
7. Go to "Collections" section on left side of Postman, and notice the new RouterOS one
8. Using postman is more up-to-you... at least the following need to be added by user for it call REST API on a RouterOS device:
- "Basic Auth" should be set either on collection (or elsewhere)
- {{baseUrl}} needs to be set to your router's IP using the environment variables in postman


Converting RAML to OpenAPI / swagger formats

This web site seem to take a RAML schema, and get then an OpenAPI schema from it:
https://mulesoft.github.io/oas-raml-converter/
which gets an OpenAPI formatted scheme from RAML.

Generated OpenAPI Schema
https://tikoci.github.io/restraml/route ... napi3.json

Although I didn't test it much, it does seems to load in Postman at least.

I'm sure there other CLI tools to do same, but RAML is support by postman which was concern.


JavaScript to generate RAML
Mainly for reference. It takes ~30 minutes, to make 30K+ REST calls, on beefy MacBook.... JS source code is in a GitHub project:
https://github.com/tikoci/restraml
Not the pretty code, but works. I'll leave containering for it for another day

Note: I would have used RouterOS script, but the 4K chucks of 6MBs didn't sound fun – but yes a RSC script, or a container, theoretically work here too. Just JS was easier/quicker since I'd done most of it a while back.

Postman in VSCode with RouterOS REST...
Using the VSCode extension for Postman also works, once the schema has been loaded:

Including postman's code generation from REST schema:



edits:
- added TODO
- fixed references to use GH project instead of a git for RAML schema download
- add screenshot of VSCode with postman plugin
- updated URL to generate OpenAPI schema
- updated to reference GitHub project.

I generated some HTML docs using the generated RAML scheme.

Generated REST API Docs
https://tikoci.github.io/restraml/

If you want to see what options are available from the REST API, this at at least shows the URL and most parameters for each endpoint.

Notes:
- descriptions are limited since "/console/inspect request=syntax" fails on some path='s. If that's fixed, there be some descriptions.

Great work! This will be very useful.

It's a start, but still needs some work... At some point I'll fix this up a bit more. I'd only done POST originally...so the GET/PATCH/DELETE methods I just quickly hacked in, but got messy.

I did convert the RAML to OpenAPI, but didn't verify it, but might be helpful since more REST tools support OpenAPI. The RAML converted to OpenAPI schema format it's here: https://tikoci.github.io/restraml/route ... napi3.json

In case it wasn't clear, schema shows all possible request parameters for HTTP endpoints. In most cases, you just a need a few & providing ALL parameters may actually NOT be valid syntax. Since goal was to know the possible options...not provide ready-to-use examples.

The current scheme is pretty vague on possible JSON responses JSON. In theory, it be possible to extract possible responses (e.g. other than just it's an object or array as in current schema). In particular for GET's it can likely know the attributes in the JSON response. Similarly it probably can do more to pull out some descriptions. Basically the "tree of commands" should be complete, at least for the router/version it was extracted.

But extracting "metadata" from "request=syntax ..." gets trickier since whole scheme in /console/inspect command is undocumented. But all the data is based on /console/inspect... if curious on how that works, see: viewtopic.php?t=199139#p1024410 – I don't actually use all of the possible data in there today.

Would be nice if MikroTik would just publish a spec instead of making you do all the hard work.

I begged them not to use a custom REST API and instead use the de-facto YANG standard. That way the router configuration could be authored and stored in a vendor-neutral format and transformed into something RouterOS can understand.

It’s sad they said no. Your solution here makes me less sad, and for that I am very grateful. If you’d like some help, in the form of technical docs, test setup, etc, hit me up on GitHub https://github.com/brotherdust

I automated schema generation on GitHub. And added a new download page that shows schema/docs for a variety of versions from 7.9 to 7.15rc4:
Downloads: https://tikoci.github.io/restraml

The source and other details are here:
GitHub Project: https://github.com/tikoci/restraml
VSCode Online View: https://github.dev/tikoci/restraml

Geeky Details... The internals of the automation are kinda nifty (IMO) & likely useful other automation using GitHub+RouterOS needs. Specifically, the GitHub Action that builds schemas/docs/etc, runs a CHR inside itself GitHub, that's used to make the need REST calls to /console/inspect. The GitHub project, specifically "Actions" shows all the gory details how the schemas are generated, with the manual-docker-in-docker.yaml doing the heavy lifting here.

Would be nice if MikroTik would just publish a spec instead of making you do all the hard work.

Very true. When I started this mini-project... I just wanted to "diff" the command tree to see what changed in CLI between versions. And... got needing to run Docker^2+QEMU+CHR somehow...

I just wanted to "diff" the command tree to see what changed in CLI between versions. And... got needing to run Docker^2+QEMU+CHR somehow...

I added a `diff` UI to the Schema Download page on GitHub, https://tikoci.github.io/restraml

It will show what commands/attributes have changed between RouterOS Versions:

Just registered to say thank you for sharing this!

Just registered to say thank you for sharing this!

Thanks!

I recently created a Postman "code generator" to convert a Postman Request JSON, into the right /tool/fetch. I'm still working on it & Postman needs to accept it. But the project would allow RouterOS /tool/fetch "code snippets" to be generated from Postman App (and other tools).

But I added a webpage that use the RouterOS Postman "codegen" to convert a `curl` command into a RouterOS /tool/fetch, as part the "Scheme Tools" series here .

Website for cURL command line into /tool/fetch command
https://tikoci.github.io/postman-code-generators/

Notes:
- URL may change in future, but that where it lives now
- It may take 15 seconds to "warm up" if no has hit the site, since I'm using glitch.com's free backend. Refreshing the page may also help.


Use Case:
Often SaaS/cloud/etc site have some curl example in there docs/UI... so above allow you can cut-and-paste the "curl version" & get a hopefully valid /tool/fetch command to use. Internally it convert the curl to a Postman JSON object, and the my RouterOS codegen convert the JSON into a /tool/fetch (to the extent fetch support it), and in a few forms to add cut-and-paste to RouterOS.

Feel to try to convert some `curl -X GET example.com`, and let me know here or in GitHub if something does not convert right.