Move API Reference (#23777)

* merge mattermost-api-reference unchanged

* api: update repostiory paths

* api: drop GitPod for api (for now)

* api: improved node_modules target

* api: relocate GitHub actions to root

* Update .github/workflows/api.yml

Co-authored-by: Antonis Stamatiou <stamatiou.antonis@gmail.com>

* fix cache-dependency-path

* adopt node-version-file

* pin versions for uses

* tidy steps/runs

* api/.gitpod.yml: tidy

* api: rm now unused .gitlab-ci.yml

---------

Co-authored-by: Antonis Stamatiou <stamatiou.antonis@gmail.com>

api/playbooks/extract.js

@@ -0,0 +1,55 @@
+'use strict';
+const YAML = require('yaml');
+const fs = require('fs');
+const fetch = require('sync-fetch');
+
+class Extractor {
+    constructor() {}
+
+    /**
+     * Write YAML data to the specified file, optionally indenting all lines by a specified amount
+     * @param filename {String} The file to write the data to
+     * @param data {Record<String, any>} An object that contains the data to be written to the file
+     * @param indent {Number} Number of spaces to left-pad each line with
+     */
+    writeFile(filename, data, indent = 0) {
+        let stringified = YAML.stringify(data, { lineWidth: 0 });
+        if (indent > 0) {
+            stringified = stringified.replace(/^(.*)$/mg, '$1'.padStart(2 + indent)) + "\n";
+        }
+        fs.writeFileSync(filename, stringified);
+        console.log("wrote file " + filename);
+    }
+
+    /**
+     * Extract various parts of an OpenAPI spec into separate files
+     * @param args {Array<String>} Program arguments
+     */
+    run(args) {
+        // Fetch the OpenAPI spec
+        const rawSpec = fetch('https://raw.githubusercontent.com/mattermost/mattermost-plugin-playbooks/master/server/api/api.yaml').text();
+        console.log("fetched Playbooks OpenAPI spec");
+        // Parse the OpenAPI spec
+        const parsed = YAML.parse(rawSpec);
+        // Extract paths
+        if ("paths" in parsed) {
+            this.writeFile("paths.yaml", parsed["paths"], 2);
+        }
+        // Extract components.schemas, components.responses, and components.securitySchemes
+        if ("components" in parsed) {
+            /** @type {Record<String,any>} */
+            const components = parsed["components"];
+            if ("schemas" in components) {
+                this.writeFile("schemas.yaml", components["schemas"]);
+            }
+            if ("responses" in components) {
+                this.writeFile("responses.yaml", components["responses"]);
+            }
+            if ("securitySchemes" in components) {
+                this.writeFile("securitySchemes.yaml", components["securitySchemes"]);
+            }
+        }
+    }
+}
+
+new Extractor().run(process.argv);

api/playbooks/merge-definitions.js

@@ -0,0 +1,61 @@
+'use strict';
+const YAML = require('yaml');
+const fs = require('fs');
+
+class MergeDefinitions {
+    constructor() {}
+
+    /**
+     * Write YAML data to the specified file
+     * @param filename {String}
+     * @param data {Record<String, any>}
+     */
+    writeFile(filename, data) {
+        fs.writeFileSync(filename, YAML.stringify(data, { lineWidth: 0 }).trimEnd());
+        console.log("wrote file " + filename);
+    }
+
+    /**
+     * Read a YAML file, parse it, and return the resulting object
+     * @param filename {String} The YAML file to read
+     * @returns {Record<String,any>} The parsed object
+     */
+    readFile(filename) {
+        const rawYaml = fs.readFileSync(filename);
+        console.log("read file " + filename);
+        return YAML.parse(rawYaml.toString());
+    }
+
+    /**
+     * Merge OpenAPI schema definitions
+     * @param args {Array<String>} Program arguments
+     */
+    run(args) {
+        if (args.length < 3) {
+            console.error("please specify an input file");
+            return;
+        }
+        if (args[2] === "") {
+            console.error("input file not specified");
+            return;
+        }
+        // read definitions.yaml
+        const parsed = this.readFile(args[2]);
+        // read schemas.yaml
+        const schemas = this.readFile("schemas.yaml");
+        // read responses.yaml
+        const responses = this.readFile("responses.yaml");
+        // read securitySchemes.yaml
+        const securitySchemes = this.readFile("securitySchemes.yaml");
+        // merge schemas with definitions.yaml
+        parsed["components"]["schemas"] = Object.assign(parsed["components"]["schemas"], schemas);
+        // merge responses with definitions.yaml
+        parsed["components"]["responses"] = Object.assign(parsed["components"]["responses"], responses);
+        // merge securitySchemes with definitions.yaml
+        parsed["components"]["securitySchemes"] = Object.assign(parsed["components"]["securitySchemes"], securitySchemes);
+        // write merged definitions to a new file
+        this.writeFile("merged-definitions.yaml", parsed);
+    }
+}
+
+new MergeDefinitions().run(process.argv);

api/playbooks/merge-tags.js

@@ -0,0 +1,53 @@
+'use strict';
+const YAML = require('yaml');
+const fs = require('fs');
+
+class MergeTags {
+    constructor() {}
+
+    /**
+     * Read a YAML file, parse it, and return the resulting object
+     * @param filename {String} The YAML file to read
+     * @returns {Record<String,any>} The parsed object
+     */
+    readFile(filename) {
+        const rawYaml = fs.readFileSync(filename);
+        console.log("read file " + filename);
+        return YAML.parse(rawYaml.toString());
+    }
+
+    /**
+     * Merge OpenAPI tags
+     * @param args {Array<String>} Program arguments
+     */
+    run(args) {
+        if (args.length < 3) {
+            console.error("please specify an input file");
+            return;
+        }
+        if (args[2] === "") {
+            console.error("input file not specified");
+            return;
+        }
+        // read introduction.yaml
+        const parsed = this.readFile(args[2]);
+        // read tags.yaml
+        const tags = this.readFile("tags.yaml");
+        if ("tags" in parsed) {
+            parsed["tags"].push(...tags["tags"]);
+        }
+        if ("x-tagGroups" in parsed) {
+            parsed["x-tagGroups"].push(...tags["x-tagGroups"]);
+        }
+        // Convert the modified object back to YAML and remove the trailing "null" as we want the
+        // "paths" field to have no value at this stage of building.
+        const yamlString =
+            YAML.stringify(parsed, { lineWidth: 0 }).
+                replace(/^paths:.*null.*$/mg, "paths: ");
+        // write out to merged-tags.yaml
+        fs.writeFileSync("merged-tags.yaml", yamlString);
+        console.log("wrote file merged-tags.yaml");
+    }
+}
+
+new MergeTags().run(process.argv);

api/playbooks/tags.yaml

@@ -0,0 +1,20 @@
+---
+tags:
+  - name: Playbooks
+    description: Playbooks
+  - name: PlaybookRuns
+    description: Playbook runs
+  - name: Internal
+    description: Internal endpoints
+  - name: Timeline
+    description: Timeline
+  - name: PlaybookAutofollows
+    description: Playbook Autofollows
+x-tagGroups:
+  - name: Playbooks
+    tags:
+      - Playbooks
+      - PlaybookRuns
+      - PlaybookAutofollows
+      - Timeline
+      - Internal