Fixes #16852: Add openapi 11 version of the API doc

api-doc/.gitignore

@@ -0,0 +1,2 @@
+/build
+/target

api-doc/Makefile

@@ -0,0 +1,14 @@
+API:=webapp relay
+
+all: $(API)
+
+$(API): clean
+	# Prepare all sources in build/ dir
+	mkdir -p build target/$@
+	cp -r ../$@/sources/api-doc build/$@
+	mkdir -p build/$@/assets
+	cp -r assets/. build/$@/assets
+	./build.py $@ build target
+
+clean:
+	rm -rf build target

api-doc/README.adoc

@@ -0,0 +1,33 @@
+= API documentation
+
+== Usage (openapi/redoc)
+
+Building the doc requires installing:
+
+```
+npm install -g redoc-cli @redocly/openapi-cli
+```
+
+* `openapi-cli` builds a single openapi file from the sources
+* `redoc-cli` produces the HTML output from the openapi file
+
+Then run:
+
+```
+make
+```
+
+And the resulting files will be in `target/`.
+
+== Sources
+
+The sources are in `{component}/sources/api-doc`. The main file is `openapi.src.yml`.
+It is then read and modified by the build process to add the documentation
+from the markdown file in `info/description`.
+
+Each Rudder branch contains the sources of the docs for the APIs introduced in
+its version.
+
+If a Rudder branch introduced several version, the latest one should be named
+`openapi.src.yml`, and previous ones `openapi-VERSION.src.yml`
+(to allow easier upmerge of changes).

api-doc/build.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+
+# loads a openapi.yml template and adds missing information to produce a valid
+# openapi.yml file.
+# Then build html docs
+
+import sys
+import yaml
+import os
+import subprocess
+import glob
+import shutil
+
+# API to build
+api = sys.argv[1]
+source_dir = sys.argv[2]
+target_dir = sys.argv[3]
+
+# source dir
+source = "%s/%s" % (source_dir, api)
+
+# Read openapi(-ver).src.yml and read versions inside.
+templates = glob.glob(source+"/openapi*.src.yml")
+
+for template in templates:
+    with open(template, 'r') as content_file:
+        main = yaml.load(content_file.read(), Loader=yaml.FullLoader)
+    version = main["info"]["version"]
+    intro_file = main["info"]["description"]
+
+    print("Building version %s from %s" % (version, template))
+
+    # Fetch introduction content
+    with open(source+'/introduction.md', 'r') as content_file:
+        intro = content_file.read()
+
+    # Add external content
+    main["info"]["description"] = intro
+
+    # Dump target in target .yml file
+    src_openapi_file = template.replace(".src", "")
+    with open(src_openapi_file, 'w') as file:
+        documents = yaml.dump(main, file)
+
+    target = "%s/%s/%s" % (target_dir, api, version)
+
+    # Build final openapi.yml
+    openapi_file = "%s/openapi.yml" % target
+    subprocess.call(["openapi", "bundle", src_openapi_file,
+                     "--output", openapi_file])
+
+    # Build doc from yaml file (with pre-rendered html)
+    html_file = "%s/openapi.html" % target
+    subprocess.call(["redoc-cli", "bundle", openapi_file,
+                     "--output", html_file,
+                     # Don't help google track our users
+                     "--disableGoogleFont",
+                     # The famous Rudder orange
+                     "--options.theme.colors.primary.main='#f08004'",
+                     # Expand success examples by default
+                     "--options.expandResponses='200,'",
+                     # More readable in central column
+                     "--options.pathInMiddlePanel=1",
+                     # Hostname is meaningless as it won't match rudder server
+                     "--options.hideHostname=1"
+                     ])
+
+    shutil.copytree("%s/assets" % source, "%s/assets" % target)

webapp/sources/api-doc/code_samples/curl/change-requests/accept.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/changeRequests --data "status=open"

webapp/sources/api-doc/code_samples/curl/change-requests/all.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/changeRequests --data "status=open"

webapp/sources/api-doc/code_samples/curl/change-requests/refuse.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request DELETE https://rudder.example.com/rudder/api/latest/changeRequests/43

webapp/sources/api-doc/code_samples/curl/change-requests/update.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/changeRequests/42  --data "name=new Name of change request" -d "description=add a new description"

webapp/sources/api-doc/code_samples/curl/compliance/global.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/compliance?prettify=true'

webapp/sources/api-doc/code_samples/curl/compliance/node.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/compliance/nodes/root?level=1'

webapp/sources/api-doc/code_samples/curl/compliance/nodes.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/compliance/nodes?level=2'

webapp/sources/api-doc/code_samples/curl/compliance/rule.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/compliance/rules/32377fd7-02fd-43d0-aab7-28460a91347b?level=2'

webapp/sources/api-doc/code_samples/curl/compliance/rules.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/compliance/rules?level=2'

webapp/sources/api-doc/code_samples/curl/datasources/all.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/datasources'

webapp/sources/api-doc/code_samples/curl/datasources/create.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request PUT https://rudder.example.com/rudder/api/latest/datasources --header "Content-type: application/json" --data @datasources.json

webapp/sources/api-doc/code_samples/curl/datasources/delete.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request DELETE https://rudder.example.com/rudder/api/latest/datasources/my-data-source

webapp/sources/api-doc/code_samples/curl/datasources/get.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/datasources/my-data-source

webapp/sources/api-doc/code_samples/curl/datasources/reload-id.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/datasources/reload/datasourceId

webapp/sources/api-doc/code_samples/curl/datasources/reload-node-id.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/nodes/nodeId/fetchData/datasourceId

webapp/sources/api-doc/code_samples/curl/datasources/reload-node.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7/fetchData

webapp/sources/api-doc/code_samples/curl/datasources/reload.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/datasources/reload

webapp/sources/api-doc/code_samples/curl/datasources/update.sh

@@ -0,0 +1,7 @@
+cat disable-datasource-1.json.json
+{
+  "description": "This data source is temporarly no more used and so disabled",
+  "enabled": false
+}
+
+curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/datasources/my-data-source --header "Content-type: application/json" --data @disable-datasource-1.json.json

webapp/sources/api-doc/code_samples/curl/directives/all.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/directives

webapp/sources/api-doc/code_samples/curl/directives/check.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/directives/17dadf50-6056-4c8b-a935-6b97d14b89a7/check  --data "displayName=Name of new directive"

webapp/sources/api-doc/code_samples/curl/directives/create.sh

@@ -0,0 +1,47 @@
+directives.json:
+
+{
+  "id": "cf2a6c72-18ae-4f82-a12c-0b887792db41",
+  "displayName": "Example Directive",
+  "shortDescription": "This in an example Directive to use in Rudder api documentation",
+  "longDescription": "",
+  "techniqueName": "genericVariableDefinition",
+  "techniqueVersion": "2.0",
+  "tags": {
+    "env" : "production",
+    "country" : "FR"
+  },
+  "parameters": {
+    "section": {
+      "name": "sections",
+      "sections": [
+        {
+          "section": {
+            "name": "Variable definition",
+            "vars": [
+              {
+                "var": {
+                  "name": "GENERIC_VARIABLE_CONTENT",
+                  "value": "new variable content"
+                }
+              },
+              {
+                "var": {
+                  "name": "GENERIC_VARIABLE_NAME",
+                  "value": "new_variable"
+                }
+              }
+            ]
+          }
+        }
+      ]
+    }
+  },
+  "priority": 3,
+  "enabled": true,
+  "system": false,
+  "policyMode": "default"
+}
+
+curl --header "X-API-Token: yourToken" --request PUT https://rudder.example.com/rudder/api/latest/directives --header "Content-type: application/json" --data @directive.json
+

webapp/sources/api-doc/code_samples/curl/directives/delete.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request DELETE https://rudder.example.com/rudder/api/latest/directives/17dadf50-6056-4c8b-a935-6b97d14b89a7

webapp/sources/api-doc/code_samples/curl/directives/get.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/directives/17dadf50-6056-4c8b-a935-6b97d14b89a7

webapp/sources/api-doc/code_samples/curl/directives/update.sh

@@ -0,0 +1,33 @@
+directive.json:
+{
+  "longDescription": "Add a loooooooooooong description",
+  "parameters": {
+    "section": {
+      "name": "sections",
+      "sections": [
+        {
+          "section": {
+            "name": "Variable definition",
+            "vars": [
+              {
+                "var": {
+                  "name": "GENERIC_VARIABLE_CONTENT",
+                  "value": "Change Variable Content"
+                }
+              },
+              {
+                "var": {
+                  "name": "GENERIC_VARIABLE_NAME",
+                  "value": "new_variable"
+                }
+              }
+            ]
+          }
+        }
+      ]
+    }
+  },
+  "priority": 5
+}
+
+curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/directives/cf2a6c72-18ae-4f82-a12c-0b887792db41 --header "Content-type: application/json" --data @directive.json

webapp/sources/api-doc/code_samples/curl/groups/all.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/groups

webapp/sources/api-doc/code_samples/curl/groups/category-id-delete.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request DELETE 'https://rudder.example.com/rudder/api/latest/groups/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5'

webapp/sources/api-doc/code_samples/curl/groups/category-id-new.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request PUT 'https://rudder.example.com/rudder/api/latest/groups/categories' --data "name=new category name" -d "parent=4306143d-eabf-4478-b7b1-1616f4aa02b5" -d "description=A new category created via API'

webapp/sources/api-doc/code_samples/curl/groups/category-id-update.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/groups/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5' --data "name=new category name"

webapp/sources/api-doc/code_samples/curl/groups/category-id.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/groups/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5'

webapp/sources/api-doc/code_samples/curl/groups/create.sh

@@ -0,0 +1,18 @@
+groups.json:
+{
+ "category": "c355f46e-11b0-4c7a-aedd-6a5f3b0303b6",
+ "displayName": "Example group",
+ "description": "This is an example Group to use in Rudder api documentation",
+ "query":
+   {"select":"node","composition":"Or","where":
+     [
+       {"objectType":"node","attribute":"nodeId","comparator":"eq","value":"1ae6ccfe-00ba-44c0-b1aa-362d2f386032"},
+       {"objectType":"node","attribute":"nodeId","comparator":"eq","value":"e4a80fd8-373e-45fc-ad94-2ae618be32e3"}
+     ]
+   },
+  "dynamic": true,
+  "enabled": true
+}
+
+curl --header "X-API-Token: yourToken" --request PUT https://rudder.example.com/rudder/api/latest/groups --header "Content-Type: application/json" --data @group.json
+

webapp/sources/api-doc/code_samples/curl/groups/delete.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request DELETE 'https://rudder.example.com/rudder/api/latest/groups/17dadf50-6056-4c8b-a935-6b97d14b89a7'

webapp/sources/api-doc/code_samples/curl/groups/id.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/groups/17dadf50-6056-4c8b-a935-6b97d14b89a7'

webapp/sources/api-doc/code_samples/curl/groups/reload.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/groups/17dadf50-6056-4c8b-a935-6b97d14b89a7/reload'

webapp/sources/api-doc/code_samples/curl/groups/tree.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET https://rudder.example.com/rudder/api/latest/groups/tree

webapp/sources/api-doc/code_samples/curl/groups/update.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/groups/17dadf50-6056-4c8b-a935-6b97d14b89a7' --data "displayName=New name of group"

webapp/sources/api-doc/code_samples/curl/inventories/info.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/

webapp/sources/api-doc/code_samples/curl/inventories/restart.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/inventories/watcher/restart'

webapp/sources/api-doc/code_samples/curl/inventories/start.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/inventories/watcher/start'

webapp/sources/api-doc/code_samples/curl/inventories/stop.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/inventories/watcher/stop'

webapp/sources/api-doc/code_samples/curl/inventories/upload.sh

@@ -0,0 +1 @@
+curl --request POST --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/inventories/upload -F "file=@inventory-file" -F "signature=@signature-file"

webapp/sources/api-doc/code_samples/curl/nodes/all.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" 'https://rudder.example.com/rudder/api/latest/nodes?where=\[\{"objectType":"node","attribute":"OS","comparator":"eq","value":"Linux"\},\{"objectType":"node","attribute":"nodeHostname","comparator":"regex","value":"node1.*"\}\]'

webapp/sources/api-doc/code_samples/curl/nodes/apply-all.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST --header "Content-Type: application/json" https://rudder.example.com/rudder/api/latest/nodes/applyPolicy

webapp/sources/api-doc/code_samples/curl/nodes/apply-id.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST --header "Content-Type: application/json" https://rudder.example.com/rudder/api/latest/nodes/root/applyPolicy

webapp/sources/api-doc/code_samples/curl/nodes/delete.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request DELETE https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7

webapp/sources/api-doc/code_samples/curl/nodes/id-update.sh

@@ -0,0 +1,16 @@
+# Given the "data.json" JSON file with content:
+{ "properties": [
+  { "name": "env_type"    , "value": "production" },
+  { "name": "shell"       , "value": "/bin/sh" },
+  { "name": "utf-8 poetry", "value": "ᚠᛇᚻ᛫ᛒᛦᚦ᛫ᚠᚱᚩᚠᚢᚱ᛫ᚠᛁᚱᚪ᛫ᚷᛖᚻᚹᛦᛚᚳᚢᛗ" }
+]
+, "policyMode" : "audit"
+}
+# Setting properties from "data.json" and policy mode to audit:
+curl --header "X-API-Token: yourToken" --request POST --header "Content-Type: application/json" https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7 --data @properties.json
+
+# Removing the key "utf-8 poetry" from the command line and updating the "env_type" one
+curl --header "X-API-Token: yourToken" --request POST --header "Content-Type: application/json" https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7 --data '{ "properties": [{ "name":"utf-8 poetry", "value":""}, {"name":"env_type", "value":"deprovisioned"}] }'
+
+# Removing the key "env_type" and changing "shell" and use default policy mode
+curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7 --data "properties=shell=/bin/false" -d "properties=env_type=" -d "policyMode=default"

webapp/sources/api-doc/code_samples/curl/nodes/id.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/nodes/17dadf50-6056-4c8b-a935-6b97d14b89a7\?include=full

webapp/sources/api-doc/code_samples/curl/nodes/pending-id.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/nodes/pending/17dadf50-6056-4c8b-a935-6b97d14b89a7 --data "status=accepted"

webapp/sources/api-doc/code_samples/curl/parameters/create-parameter.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --header "Content-Type: application/json" --request PUT https://rudder.example.com/rudder/api/latest/parameters --data @JSON-file-name

webapp/sources/api-doc/code_samples/curl/parameters/delete-parameter.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request DELETE https://rudder.example.com/rudder/api/latest/parameters/ParameterId

webapp/sources/api-doc/code_samples/curl/parameters/get-parameter.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/parameters/ParameterId

webapp/sources/api-doc/code_samples/curl/parameters/list-parameters.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" https://rudder.example.com/rudder/api/latest/parameters

webapp/sources/api-doc/code_samples/curl/parameters/modify-parameter.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST https://rudder.example.com/rudder/api/latest/parameters/ParameterId --data "value=### Edited by Rudder ###"

webapp/sources/api-doc/code_samples/curl/rules/all.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request GET 'https://rudder.example.com/rudder/api/latest/rules'

webapp/sources/api-doc/code_samples/curl/rules/category-id-delete.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request DELETE 'https://rudder.example.com/rudder/api/latest/rules/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5?prettify=true'

webapp/sources/api-doc/code_samples/curl/rules/category-id-new.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/rules/categories' --data "name=new category" -d "parent=4306143d-eabf-4478-b7b1-1616f4aa02b5" -d "description=A new category created via API'

webapp/sources/api-doc/code_samples/curl/rules/category-id-update.sh

@@ -0,0 +1 @@
+curl --header "X-API-Token: yourToken" --request POST 'https://rudder.example.com/rudder/api/latest/rules/categories/4306143d-eabf-4478-b7b1-1616f4aa02b5?prettify=true' --data "name=new category name"