@redpanda-data/docs-extensions-and-macros 4.15.10 → 4.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.15.10",
+  "version": "4.16.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/bundle-openapi.js

@@ -248,6 +248,55 @@ function createEntrypoint(tempDir, apiSurface) {
   return fragmentFiles;
 }
 
+/**
+ * Wrap $ref siblings into allOf to preserve field-level descriptions.
+ *
+ * In OpenAPI 3.0, sibling properties next to $ref are ignored per spec.
+ * Some renderers (e.g. Bump.sh) follow this behavior, displaying the generic
+ * description from the referenced schema instead of field-level overrides.
+ * This function transforms { $ref, description, ... } into
+ * { allOf: [{ $ref }], description, ... } so renderers pick up field-level
+ * descriptions correctly.
+ *
+ * @param {*} node - Any value from the parsed OpenAPI spec.
+ * @returns {*} The transformed value (mutates in place for objects).
+ */
+function wrapRefSiblings(node) {
+  if (node === null || typeof node !== 'object') {
+    return node;
+  }
+
+  if (Array.isArray(node)) {
+    node.forEach((item, i) => {
+      node[i] = wrapRefSiblings(item);
+    });
+    return node;
+  }
+
+  // Check if this object has $ref with sibling properties that need wrapping
+  if (node['$ref'] && typeof node['$ref'] === 'string') {
+    const keys = Object.keys(node);
+    const hasSiblings = keys.length > 1;
+
+    if (hasSiblings) {
+      // Skip if allOf already exists — assumes a pre-existing structure
+      // from the source spec that should not be modified.
+      if (!node.allOf) {
+        const ref = node['$ref'];
+        delete node['$ref'];
+        node.allOf = [{ '$ref': ref }];
+      }
+    }
+  }
+
+  // Recurse into all object values
+  for (const key of Object.keys(node)) {
+    node[key] = wrapRefSiblings(node[key]);
+  }
+
+  return node;
+}
+
 /**
  * Bundle one or more OpenAPI fragment files into a single bundled YAML using a selected external bundler.
  *
@@ -529,6 +578,9 @@ function postProcessBundle(filePath, options, quiet = false) {
     bundle.info['x-generated-at'] = new Date().toISOString();
     bundle.info['x-generator'] = 'redpanda-docs-openapi-bundler';
 
+    // Wrap $ref siblings into allOf so renderers display field descriptions
+    bundle = wrapRefSiblings(bundle);
+
     // Sort keys for deterministic output
     const sortedBundle = sortObjectKeys(bundle);
     
@@ -776,6 +828,7 @@ module.exports = {
   normalizeTag,
   getMajorMinor,
   sortObjectKeys,
+  wrapRefSiblings,
   detectBundler,
   createEntrypoint,
   postProcessBundle