refactor: migrate Tasklist API Explorer into versioned docs (#3569)

* refactor: generalize the strategy for generating api docs, and implement zeebe as an example.

* docs: docs on docs for the new model of generating API explorers

* refactor: rewrite tasklist API Explorer generation to take advantage of new pipeline

* refactor: migrate tasklist REST API Explorer into v8.4 docs

* refactor: migrate alpha tasklist REST API Explorer into vNext docs

* cleanup: remove unused tasklist api docs

* cleanup: revert 'show correct version for Tasklist API Exlporer in navbar'

* refactor: remove API Explorer references from tasklist rest overview

* fix: broken links from moving the Tasklist API Explorer

* chore: redirect rules for moving the tasklist api explorer

* I changed my mind: put back the api explorer intro paragraph, send it to the new location

* feedback: move specs above migration in left nav

api/generate-api-docs.js

@@ -3,9 +3,11 @@ const { execSync } = require("child_process");
 // More strategies to come, for other APIs.
 const operate = require("./operate/generation-strategy");
 const zeebe = require("./zeebe/generation-strategy");
+const tasklist = require("./tasklist/generation-strategy");
 const apiStrategies = {
   operate,
   zeebe,
+  tasklist,
 };
 
 // Execute a command as if we were in the terminal

api/tasklist/generation-strategy.js

@@ -0,0 +1,32 @@
+const replace = require("replace-in-file");
+const removeDuplicateVersionBadge = require("../remove-duplicate-version-badge");
+const { makeServerDynamic } = require("../make-server-dynamic");
+
+const outputDir = "docs/apis-tools/tasklist-api-rest/specifications";
+const specFile = "api/tasklist/tasklist-openapi.yaml";
+
+function preGenerateDocs() {
+  fixImproperlyFormattedBreaks();
+  makeServerDynamic(specFile);
+}
+
+function postGenerateDocs() {
+  removeDuplicateVersionBadge(`${outputDir}/tasklist-rest-api.info.mdx`);
+}
+
+module.exports = {
+  outputDir,
+  preGenerateDocs,
+  postGenerateDocs,
+};
+
+function fixImproperlyFormattedBreaks() {
+  // The source spec has many `<br>` tags in it, which is valid HTML,
+  //   but docusaurus does not like it. Make them `<br/>` instead.
+  console.log("fixing break tags...");
+  replace.sync({
+    files: specFile,
+    from: /<br>/g,
+    to: "<br/>",
+  });
+}