feat: add Unified REST API docs

* Adds the unified REST API explorer to the list of APIs.

api/generate-api-docs.js

@@ -4,10 +4,12 @@ const { execSync } = require("child_process");
 const operate = require("./operate/generation-strategy");
 const zeebe = require("./zeebe/generation-strategy");
 const tasklist = require("./tasklist/generation-strategy");
+const unified = require("./unified/generation-strategy");
 const apiStrategies = {
   operate,
   zeebe,
   tasklist,
+  unified,
 };
 
 // Execute a command as if we were in the terminal

api/unified/generation-strategy.js

@@ -0,0 +1,48 @@
+const removeDuplicateVersionBadge = require("../remove-duplicate-version-badge");
+const replace = require("replace-in-file");
+const outputDir = "docs/apis-tools/unified-api-rest/specifications";
+const specFile = "api/unified/unified-openapi.yaml";
+
+function preGenerateDocs() {
+  hackChangesetDescription();
+}
+
+function postGenerateDocs() {
+  removeDuplicateVersionBadge(`${outputDir}/unified-rest-api.info.mdx`);
+}
+
+module.exports = {
+  outputDir,
+  preGenerateDocs,
+  postGenerateDocs,
+};
+
+function hackChangesetDescription() {
+  // This is a temporary hack, until https://github.com/camunda/camunda-docs/issues/3568 is resolved.
+  //   The OpenAPI generator plugin we're using does not use the correct `description` property
+  //   for the `UserTaskUpdateRequest` object. Instead of picking up the actual property description,
+  //   it picks up the description of the first merged schema in the `allOf` property (i.e. from the `Changeset` schema).
+  // This adjustment replaces the description of the `Changeset` schema with the current description of
+  //   the `UserTaskUpdateRequest.changeset` property.
+  console.log("hacking changeset description...");
+  replace.sync({
+    files: `${specFile}`,
+    from: /^      description: A map of changes.$/m,
+    to: `      description: |
+        JSON object with changed task attribute values.
+
+        The following attributes can be adjusted with this endpoint, additional attributes
+        will be ignored:
+
+        * \`candidateGroups\` - reset by providing an empty list
+        * \`candidateUsers\` - reset by providing an empty list
+        * \`dueDate\` - reset by providing an empty String
+        * \`followUpDate\` - reset by providing an empty String
+
+        Providing any of those attributes with a \`null\` value or omitting it preserves
+        the persisted attribute's value.
+
+        The assignee cannot be adjusted with this endpoint, use the Assign task endpoint.
+        This ensures correct event emission for assignee changes.`,
+  });
+}