snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/site/scripts/build-openapi.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Builds the merged OpenAPI spec by delegating to the canonical api/Makefile,
+ * then sanitizes the output for MDX compatibility.
+ *
+ * Sanitization (description / summary / title strings):
+ *   1) Embedded "..." breaks docusaurus-plugin-openapi-docs frontmatter quoting.
+ *      Replace with curly quotes (“ / ”).
+ *   2) Markdown autolinks like </api/v4/foo> are parsed as JSX closing tags by MDX.
+ *      Escape bare < not followed by a letter or ! to &lt;.
+ *
+ * Usage:  node scripts/build-openapi.mjs   (from docs/site/)
+ * Output: docs/site/openapi/mattermost-openapi-v4.yaml
+ */
+
+import {execSync} from 'node:child_process';
+import {readFileSync, writeFileSync, mkdirSync, existsSync} from 'node:fs';
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {parse, stringify} from 'yaml';
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url)); // docs/site/scripts
+const DOCS_SITE_DIR = resolve(SCRIPT_DIR, '..'); // docs/site
+const MONOREPO_ROOT = resolve(SCRIPT_DIR, '../../..'); // mattermost/
+const API_ROOT = resolve(MONOREPO_ROOT, 'api'); // mattermost/api
+const RAW_SPEC_PATH = resolve(API_ROOT, 'v4/html/static/mattermost-openapi-v4.yaml'); // make's own output
+const SANITIZED_SPEC_PATH = resolve(DOCS_SITE_DIR, 'openapi/mattermost-openapi-v4.yaml'); // what Docusaurus reads
+
+function walkStrings(node, fn, key) {
+  if (typeof node === 'string') return fn(node, key);
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) node[i] = walkStrings(node[i], fn, key);
+    return node;
+  }
+  if (node && typeof node === 'object') {
+    for (const [k, v] of Object.entries(node)) node[k] = walkStrings(v, fn, k);
+    return node;
+  }
+  return node;
+}
+
+function main() {
+  if (!existsSync(API_ROOT)) {
+    console.error(`[openapi] api/ directory not found at ${API_ROOT}`);
+    console.error('[openapi] Ensure you are running from within the mattermost monorepo.');
+    process.exit(1);
+  }
+
+  console.log(`[openapi] Building OpenAPI spec via make -C ${API_ROOT} build`);
+  execSync(`make -C ${API_ROOT} build`, {stdio: 'inherit'});
+
+  if (!existsSync(RAW_SPEC_PATH)) {
+    console.error(`[openapi] Expected make output not found: ${RAW_SPEC_PATH}`);
+    process.exit(1);
+  }
+
+  console.log('[openapi] Sanitizing for MDX compatibility ...');
+  const doc = parse(readFileSync(RAW_SPEC_PATH, 'utf8'));
+
+  let quoteFixes = 0;
+  let autolinkFixes = 0;
+  walkStrings(doc, (value, key) => {
+    if (key !== 'description' && key !== 'summary' && key !== 'title') return value;
+    let v = value;
+    if (v.includes('"')) {
+      const fixed = v.replace(/"([^"]*)"/g, '“$1”');
+      if (fixed !== v) { quoteFixes++; v = fixed; }
+    }
+    if (/<[^a-zA-Z!]/.test(v)) {
+      const fixed = v.replace(/<(?=[^a-zA-Z!])/g, '&lt;');
+      if (fixed !== v) { autolinkFixes++; v = fixed; }
+    }
+    return v;
+  });
+
+  console.log(`[openapi] Sanitized: quotes=${quoteFixes}, autolinks=${autolinkFixes}`);
+
+  mkdirSync(dirname(SANITIZED_SPEC_PATH), {recursive: true});
+  writeFileSync(SANITIZED_SPEC_PATH, stringify(doc, {lineWidth: 0}));
+
+  const sizeMb = (readFileSync(SANITIZED_SPEC_PATH).length / 1024 / 1024).toFixed(2);
+  console.log(`[openapi] Wrote ${sizeMb} MB → ${SANITIZED_SPEC_PATH}`);
+}
+
+main();