search

tikoci / restraml

RouterOS REST API "Schema Tools"
https://tikoci.github.io/restraml/
The Unlicense
12 stars 0 forks source link

readme

RouterOS API Schema Tools

NEW!   diff RouterOS Commands

The project web site has an diff tool that compares the output of /console/inspect between RouterOS Versions.

Download Schemas

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:

There may be a base and +extra schema download links.

Usage with Postman

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.

What about OpenAPI?

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.

Build

Generating the RAML file

  1. Install Bun
  2. Clone this repository
  3. Install js-yaml: bun install js-yaml
  4. Run 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.

  5. Open a pull request to add the RAML file to this repository if it's missing 😉

Generating the HTML page

  1. Follow steps 1-2 above, or 1-4 if this repository doesn't currently contain a RAML file for your RouterOS version.
  2. Install raml2html and raml2html-slate-theme: bun install raml2html raml2html-slate-theme
  3. Generate the HTML page with raml2html: 
    raml2html --theme raml2html-slate-theme <RAML file> > <HTML file>
# Example:
raml2html --theme raml2html-slate-theme ros-rest-all.raml > ros-rest.all.html

Implementation

Schema Generation

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

GitHub Actions is used to build the schema published on this project's website:

[!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.

Pages

The website for the project - with downloadable schemas – is from the /docs directory in repo.