diff
RouterOS CommandsThe project web site has an diff
tool that compares the output of /console/inspect
between RouterOS Versions.
Pre-build schema files for RouterOS REST API are available on this project's website at https://tikoci.github.io/restraml
[!TIP] File an issue in this project, if you'd like a specific version built.
Included are three files:
RAML
- schema in RAML 1.0 format, used in tools like PostmanHTML
- documentation, generated from the schemaOAS2
- OpenAPI 2.0 format, converted from RAMLJSON
- intermediate raw data from RouterOS's /console/inspect
in JSON format, for use with data analyticsMIB
- link to official Mikrotik MIB for SNMPThere may be a base and +extra schema download links.
routeros.npk
package routeros, dude, container, rose-storage, gps, lora, calea, user-manager, routeros, ups, iot, wifiwave2, tr069-client
For detailed instructions on using the RAML schema with Postman, see this forum article: https://forum.mikrotik.com/viewtopic.php?p=1041886
[!WARNING]
Ironically, the RouterOS schema uncovered a bug in the most recent version of Postman that does not allow directly importing a RAML schema. Postman is working on a fix. Any existing loaded schema still works. Postman version 11.0.12 and below work fine.
To import this schema into Postman App 11.1.14 or greater, the RAML schema must be indirectly as an "API", and then from API creating a collection from the API - rather than directly importing the RAML, see raml1-to-postman issue #84 showing the process, including a video of the process.
OpenAPI 2.0 schema RouterOS REST API is available on Downloads tagged as OAS2
. The OpenAPI schema is generated from the RAML schema. Only +extra schema version is available.
Should OpenAPI 3.0 (OAS3
) be needed, this can be done using MuleSoft's online converter here:
https://mulesoft.github.io/oas-raml-converter
However, the OAS3
produced does not validate using webapi-parser
tool, but will load in Postman.
[!TIP]
Generally, if a RAML schema is supported by your tool, use RAML schema as other formats may be further losy.
js-yaml
:
bun install js-yaml
rest2raml.js
like so:
URLBASE=https://<IP or DNS name>/rest BASICAUTH=<user>:<pass> bun rest2raml.js
# Example:
URLBASE=https://192.168.88.1/rest BASICAUTH=admin:h3llow0rld bun rest2raml.js
Wait a while for this code to run. It could take as long as an hour to process the entire schema.
raml2html
and raml2html-slate-theme
:
bun install raml2html raml2html-slate-theme
raml2html
:
raml2html --theme raml2html-slate-theme <RAML file> > <HTML file>
# Example:
raml2html --theme raml2html-slate-theme ros-rest-all.raml > ros-rest.all.html
The schema generation is done via JavaScript, specifically using bun
, in rest2raml.js
. The code connects to RouterOS via REST API, to use the /console/inspect
command to traverse the "AST" for RouterOS config. The results of this intermediate phase are stored in an inspect.json
, as retrieved from the router. With the inspect.json, rest2raml.js
then builds that data into a RAML schema for API tools.
[!WARNING] The generated schema is more for convenience than validation. Generation is limited to the data available from
/console/inspect
, and what's reasonable to deduce. So there is not perfect fidelity between schema and API. For example, while there are required and optional parameters, all parameters are marked as optional in the schema. As a result, all attributes are generally shown - while using all of them is likely to be invalid.
GitHub Actions is used to build the schema published on this project's website:
manual-from-docker-in-docker.yaml
Workflow - start a RouterOS CHR (via docker-compose and QEMU) within the build, and then rest2raml.js
uses the "internal" CHR to generate the schema, without any external resources needed.manual-from-extra-docker-in-docker.yaml
Workflow - same as above, except CHR is loaded with extra-packages prior to schema generationmanual-from-secrets.yaml
Workflow - uses GitHub Secret with information to connection to a RouterOS device on internet[!NOTE]
All actions use only
workflow_dispatch
, so new generation is still manually triggered by providing a version on the Action page in GitHub. Only the repo owner can do this.
The website for the project - with downloadable schemas – is from the /docs
directory in repo.