Merge pull request #1 from tigattack/docs

Add/update usage docs, from PR. Thanks @tigattack!
tikoci · May 21, 2024 · e6b218e · e6b218e
2 parents a168dd3 + 798035c
commit e6b218e
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -1,2 +1,29 @@
 # restraml
 RouterOS REST API "Schema Tools"
+
+## Generating the RAML file
+
+1. Install [Bun](https://bun.sh/)
+2. Clone this repository
+3. Install `js-yaml`:  
+  `bun install js-yaml`
+4. Run `rest2raml.js` like so:
+   ```sh
+   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 as 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`:
+  ```sh
+  raml2html --theme raml2html-slate-theme <RAML file> > <HTML file>
+  # Example:
+  raml2html --theme raml2html-slate-theme ros-rest-all.raml > ros-rest.all.html
+  ```
diff --git a/rest2raml.js b/rest2raml.js
@@ -7,14 +7,14 @@ const argPath = process.argv.slice(2)
 
 async function main() {
   // STEP ZERO: calling the script "manually"...
-  //    a. install bun (on MacOS, "brew install bun")
-  //    b. save script this to a new directory, like ~/ros2rest/...
+  //    a. install bun (on MacOS, "brew install oven-sh/bun/bun")
+  //    b. save script this to a new directory, like ~/rest2raml/...
   //    c. install YAML parse, "bun install js-yaml"
   //    d. Router's IP and authentication are provided by env variables that are provide in shell:
-  //       >  URLBASE=https://change.me/rest BASICAUTH=admin:changeme bun ros2rest.js
+  //       >  URLBASE=https://change.me/rest BASICAUTH=admin:changeme bun rest2raml.js
   //    e. Wait a while as for this code to run – may take an HOUR for entire schema to process
-  //    f. Optionally, ros2rest.js takes args with path to start out, seperated by *spaces*:
-  //       >  bun ros2rest.js ip address
+  //    f. Optionally, rest2raml.js takes args with path to start out, seperated by *spaces*:
+  //       >  bun rest2raml.js ip address
   //  So, assuming, done getting version for router should work...
   const ver = await fetchVersion()
   console.log(`Using version ${ver}...`)