docusaurus-plugin-generate-schema-docs 1.1.1 → 1.3.0

package/helpers/processSchema.js

@@ -0,0 +1,32 @@
+import $RefParser from '@apidevtools/json-schema-ref-parser';
+import mergeJsonSchema from 'json-schema-merge-allof';
+
+/**
+ * Processes a JSON schema file by bundling external references,
+ * dereferencing internal references, and merging allOf properties.
+ *
+ * @param {string} filePath Path to the JSON schema file.
+ * @returns {Promise<object>} The processed (merged) schema.
+ */
+export default async function processSchema(filePath) {
+  // 1. Bundle all external references into a single, self-contained schema
+  const bundledSchema = await $RefParser.bundle(filePath, {
+    mutateInputSchema: false,
+  });
+
+  // 2. Dereference the bundled schema to resolve internal refs for allOf merging
+  const dereferencedSchema = await $RefParser.dereference(bundledSchema, {
+    dereference: {
+      circular: 'ignore', // Keep recursive parts as $refs
+    },
+  });
+
+  // Then merge allOf properties
+  const mergedSchema = mergeJsonSchema(dereferencedSchema, {
+    resolvers: {
+      defaultResolver: mergeJsonSchema.options.resolvers.title,
+    },
+  });
+
+  return mergedSchema;
+}

package/helpers/schema-doc-template.js

@@ -0,0 +1,36 @@
+export default function MdxTemplate(data) {
+  const {
+    schema,
+    mergedSchema,
+    editUrl,
+    file,
+    topPartialImport,
+    bottomPartialImport,
+    topPartialComponent,
+    bottomPartialComponent,
+  } = data;
+
+  return `---
+title: ${schema.title}
+description: ${JSON.stringify(schema.description)}
+sidebar_label: ${schema.title}
+custom_edit_url: ${editUrl}
+---
+
+import SchemaViewer from '@theme/SchemaViewer';
+import SchemaJsonViewer from '@theme/SchemaJsonViewer';
+${topPartialImport}
+${bottomPartialImport}
+
+# ${schema.title}
+
+${schema.description}
+
+${topPartialComponent}
+
+<SchemaViewer schema={${JSON.stringify(mergedSchema)}} />
+<SchemaJsonViewer schema={${JSON.stringify(schema)}} />
+
+${bottomPartialComponent}
+`;
+}

package/helpers/schema-processing.js

@@ -0,0 +1,75 @@
+import path from 'path';
+import processSchema from './processSchema.js';
+
+export function slugify(text) {
+  if (!text) {
+    return 'option';
+  }
+  return text
+    .toString()
+    .toLowerCase()
+    .replace(/\s+/g, '-') // Replace spaces with -
+    .replace(/[^\w\-]+/g, '') // Remove all non-word chars
+    .replace(/\-\-+/g, '-') // Replace multiple - with single -
+    .replace(/^-+/, '') // Trim - from start of text
+    .replace(/-+$/, ''); // Trim - from end of text
+}
+
+export function fixRefs(obj, basePath) {
+  for (const key in obj) {
+    if (
+      key === '$ref' &&
+      typeof obj[key] === 'string' &&
+      !obj[key].startsWith('#') &&
+      !obj[key].startsWith('http')
+    ) {
+      obj[key] = path.resolve(basePath, obj[key]);
+    } else if (typeof obj[key] === 'object' && obj[key] !== null) {
+      fixRefs(obj[key], basePath);
+    }
+  }
+}
+
+export async function processOneOfSchema(schema, filePath) {
+  const processedSchemas = [];
+  const choiceType = schema.oneOf ? 'oneOf' : null;
+
+  if (choiceType) {
+    const parentWithoutChoice = { ...schema };
+    delete parentWithoutChoice[choiceType];
+
+    for (const option of schema[choiceType]) {
+      let resolvedOption = option;
+      if (option.$ref && !option.$ref.startsWith('#')) {
+        const refPath = path.resolve(path.dirname(filePath), option.$ref);
+        resolvedOption = await processSchema(refPath);
+      }
+
+      // Merge the parent schema with the resolved option schema
+      const newSchema = { ...parentWithoutChoice, ...resolvedOption };
+      newSchema.properties = {
+        ...parentWithoutChoice.properties,
+        ...resolvedOption.properties,
+      };
+
+      let slug;
+      const hadId = resolvedOption.$id && resolvedOption.$id.endsWith('.json');
+      if (hadId) {
+        slug = path.basename(resolvedOption.$id, '.json');
+      } else {
+        slug = slugify(newSchema.title);
+      }
+
+      if (!hadId) {
+        newSchema.$id = `${schema.$id}#${slug}`;
+      }
+
+      processedSchemas.push({
+        slug,
+        schema: newSchema,
+      });
+    }
+  }
+
+  return processedSchemas;
+}

package/helpers/schemaToExamples.js

@@ -0,0 +1,99 @@
+import buildExampleFromSchema from './buildExampleFromSchema';
+
+/**
+ * This is the main helper that generates a list of complete example objects,
+ * grouped by the property that contains the choice.
+ *
+ * @param {object} rootSchema The complete schema for the event.
+ * @returns {object[]} An array of group objects.
+ */
+export function schemaToExamples(rootSchema) {
+  const choicePoints = [];
+
+  // 1. Find all choice points in the schema recursively
+  function findChoices(subSchema, path = []) {
+    if (!subSchema) return;
+
+    // First, check for choices at the current schema level
+    const choiceType = subSchema.oneOf
+      ? 'oneOf'
+      : subSchema.anyOf
+        ? 'anyOf'
+        : null;
+    if (choiceType) {
+      choicePoints.push({ path, schema: subSchema });
+    }
+
+    // Then, recurse into any nested properties
+    if (subSchema.properties) {
+      for (const [key, propSchema] of Object.entries(subSchema.properties)) {
+        findChoices(propSchema, [...path, 'properties', key]);
+      }
+    }
+  }
+
+  findChoices(rootSchema);
+
+  // 2. If no choices are found, generate a single default example
+  if (choicePoints.length === 0) {
+    const example = buildExampleFromSchema(rootSchema);
+    if (example && Object.keys(example).length > 0) {
+      // Return in the same group structure for consistency
+      return [
+        {
+          property: 'default',
+          options: [{ title: 'Example', example }],
+        },
+      ];
+    }
+    return [];
+  }
+
+  // 3. Map each found choice point to a "group" of examples
+  return choicePoints.map(({ path, schema }) => {
+    const choiceType = schema.oneOf ? 'oneOf' : 'anyOf';
+    const choices = schema[choiceType];
+    const propertyName = path.length > 0 ? path[path.length - 1] : 'root';
+
+    // For each option within the choice, generate a complete example
+    const options = choices.map((option) => {
+      // Create a deep copy of the root schema to modify for this specific example
+      const schemaVariant = JSON.parse(JSON.stringify(rootSchema));
+
+      // If path is empty, the choice is at the root of the schema.
+      if (path.length === 0) {
+        // Merge the chosen option's properties into the root properties
+        schemaVariant.properties = {
+          ...schemaVariant.properties,
+          ...option.properties,
+        };
+        // Remove the choice block from the root
+        delete schemaVariant.oneOf;
+        delete schemaVariant.anyOf;
+      } else {
+        // The choice is nested. Find the parent of the choice block in the copied schema.
+        let parentOfChoice = schemaVariant;
+        for (let i = 0; i < path.length; i++) {
+          parentOfChoice = parentOfChoice[path[i]];
+        }
+
+        // Delete the choice keywords and merge the selected option.
+        // This preserves other properties on the parent (like `type` and `description`).
+        delete parentOfChoice.oneOf;
+        delete parentOfChoice.anyOf;
+        Object.assign(parentOfChoice, option);
+      }
+
+      const example = buildExampleFromSchema(schemaVariant);
+      return {
+        title: option.title || 'Option',
+        example,
+      };
+    });
+
+    return {
+      property: propertyName,
+      options,
+    };
+  });
+}

package/helpers/schemaToTableData.js

@@ -0,0 +1,311 @@
+import { getConstraints } from './getConstraints';
+
+function processOptions(
+  choices,
+  level,
+  path,
+  isNestedInProperty,
+  requiredArray = [],
+  continuingLevels = [],
+) {
+  return choices.map((optionSchema, index) => {
+    const optionTitle = optionSchema.title || 'Option';
+
+    // Determine if this is the last option in the list.
+    // If it is NOT the last option, its children must not close the visual tree branch.
+    const isLastOption = index === choices.length - 1;
+
+    let optionRows = [];
+
+    // This is a primitive type (string, number, etc.) within a choice
+    if (optionSchema.type && !optionSchema.properties) {
+      const isRequired = requiredArray.includes(path[path.length - 1]);
+      const constraints = getConstraints(optionSchema);
+      if (isRequired) {
+        constraints.unshift('required');
+      }
+
+      optionRows.push({
+        type: 'property',
+        // The name of the property is the name of the parent property that holds the choice
+        name: path.length > 0 ? path[path.length - 1] : optionTitle,
+        path: [...path, `(${optionTitle})`],
+        // If it's a top-level choice (like user_id), the level is the same as the choice itself.
+        // Otherwise, it's nested.
+        level: level,
+        required: isRequired,
+        propertyType: optionSchema.type,
+        description: optionSchema.description,
+        example: optionSchema.examples || optionSchema.example,
+        constraints: constraints,
+        isLastInGroup: isLastOption, // Updated: Uses the calculated flag instead of always true
+        hasChildren: false,
+        containerType: null,
+        continuingLevels: [...continuingLevels],
+      });
+    } else {
+      // This is a complex object within a choice
+      optionRows = schemaToTableData(
+        optionSchema,
+        // If nested in a property (like payment_method), the sub-properties start at the same level as the choice
+        // Otherwise, they are one level deeper.
+        level,
+        isNestedInProperty ? [] : path,
+        continuingLevels,
+        isLastOption,
+      );
+    }
+
+    return {
+      title: optionTitle,
+      description: optionSchema.description,
+      rows: optionRows,
+    };
+  });
+}
+
+export function schemaToTableData(
+  schema,
+  level = 0,
+  path = [],
+  parentContinuingLevels = [],
+  isLastOption = true,
+) {
+  const flatRows = [];
+
+  function isEffectivelyEmpty(schemaNode) {
+    if (
+      schemaNode.type !== 'object' &&
+      typeof schemaNode.properties === 'undefined'
+    ) {
+      return false;
+    }
+    if (schemaNode.oneOf || schemaNode.anyOf) {
+      return false;
+    }
+    if (
+      !schemaNode.properties ||
+      Object.keys(schemaNode.properties).length === 0
+    ) {
+      return true;
+    }
+    return Object.values(schemaNode.properties).every(isEffectivelyEmpty);
+  }
+
+  function buildRows(
+    subSchema,
+    currentLevel,
+    currentPath,
+    requiredFromParent = [],
+    continuingLevels = [],
+  ) {
+    if (!subSchema) return;
+
+    if (subSchema.properties) {
+      const propKeys = Object.keys(subSchema.properties);
+      const hasSiblingChoices = !!(subSchema.oneOf || subSchema.anyOf);
+
+      // Filter out properties that should be skipped to get accurate count
+      const visiblePropKeys = propKeys.filter((name) => {
+        const propSchema = subSchema.properties[name];
+        return !(
+          propSchema['x-gtm-clear'] === true && isEffectivelyEmpty(propSchema)
+        );
+      });
+
+      visiblePropKeys.forEach((name, index) => {
+        const propSchema = subSchema.properties[name];
+        const newPath = [...currentPath, name];
+
+        const isLastProp =
+          index === visiblePropKeys.length - 1 && !hasSiblingChoices;
+
+        // Updated Logic:
+        // A property is visually "last" only if it is the last property
+        // AND (it is deeper in the hierarchy OR the parent option itself is the last one).
+        const isLast = isLastProp && (currentLevel !== level || isLastOption);
+
+        const isChoiceWrapper = !!(propSchema.oneOf || propSchema.anyOf);
+
+        // Determine if this property has children and what type
+        const hasNestedProperties = !!propSchema.properties;
+        const hasArrayItems =
+          propSchema.type === 'array' && !!propSchema.items?.properties;
+        const hasNestedChoice = isChoiceWrapper;
+        const hasChildren =
+          hasNestedProperties || hasArrayItems || hasNestedChoice;
+
+        // Determine container type for the symbol
+        let containerType = null;
+        if (
+          hasNestedProperties ||
+          (isChoiceWrapper && propSchema.type === 'object')
+        ) {
+          containerType = 'object';
+        } else if (hasArrayItems) {
+          containerType = 'array';
+        }
+
+        // Calculate continuing levels for children
+        // If this is not the last item, add current level to continuing levels for children
+        // If this IS the last item, remove the immediate parent level (currentLevel - 1) because
+        // that line stops at this item and should not continue through its children
+        const childContinuingLevels = isLast
+          ? continuingLevels.filter((lvl) => lvl !== currentLevel - 1)
+          : [...continuingLevels, currentLevel];
+
+        // This is a "simple" choice property like user_id.
+        // It gets unwrapped into a choice row directly.
+        if (
+          isChoiceWrapper &&
+          !propSchema.properties &&
+          propSchema.type !== 'object'
+        ) {
+          const choiceType = propSchema.oneOf ? 'oneOf' : 'anyOf';
+          const choices = propSchema[choiceType];
+          flatRows.push({
+            type: 'choice',
+            choiceType,
+            path: newPath,
+            level: currentLevel,
+            title: propSchema.title,
+            description: propSchema.description,
+            isLastInGroup: isLast,
+            hasChildren: false,
+            containerType: null,
+            continuingLevels: [...continuingLevels],
+            options: processOptions(
+              choices,
+              currentLevel,
+              newPath,
+              false,
+              subSchema.required || requiredFromParent,
+              childContinuingLevels,
+            ),
+          });
+        } else {
+          // This is a "normal" property or a complex one with a nested choice.
+          const isRequired =
+            (subSchema.required || requiredFromParent)?.includes(name) || false;
+          const constraints = getConstraints(propSchema);
+          if (isRequired) {
+            constraints.unshift('required');
+          }
+
+          flatRows.push({
+            type: 'property',
+            name,
+            path: newPath,
+            level: currentLevel,
+            required: isRequired,
+            propertyType:
+              propSchema.type || (propSchema.enum ? 'enum' : 'object'),
+            description: propSchema.description,
+            example: propSchema.examples || propSchema.example,
+            constraints,
+            isLastInGroup: isLast,
+            hasChildren,
+            containerType,
+            continuingLevels: [...continuingLevels],
+          });
+
+          if (propSchema.properties) {
+            buildRows(
+              propSchema,
+              currentLevel + 1,
+              newPath,
+              propSchema.required,
+              childContinuingLevels,
+            );
+          } else if (
+            propSchema.type === 'array' &&
+            propSchema.items?.properties
+          ) {
+            buildRows(
+              propSchema.items,
+              currentLevel + 1,
+              [...newPath, '[n]'],
+              propSchema.items.required,
+              childContinuingLevels,
+            );
+          } else if (isChoiceWrapper) {
+            // This handles the "complex" choice property like payment_method.
+            // A property row has already been created above, now we add the choice row.
+            const choiceType = propSchema.oneOf ? 'oneOf' : 'anyOf';
+            const choices = propSchema[choiceType];
+            flatRows.push({
+              type: 'choice',
+              choiceType,
+              path: [...newPath, choiceType], // Make path unique
+              level: currentLevel + 1,
+              title: propSchema.title,
+              description: null,
+              isLastInGroup: true,
+              hasChildren: false,
+              containerType: null,
+              continuingLevels: childContinuingLevels,
+              options: processOptions(
+                choices,
+                currentLevel + 1,
+                newPath,
+                true,
+                propSchema.required,
+                childContinuingLevels,
+              ),
+            });
+          }
+        }
+      });
+    }
+
+    // This handles choices at the root of a schema
+    const choiceType = subSchema.oneOf
+      ? 'oneOf'
+      : subSchema.anyOf
+        ? 'anyOf'
+        : null;
+    if (choiceType) {
+      const choices = subSchema[choiceType];
+      flatRows.push({
+        type: 'choice',
+        choiceType,
+        path: currentPath,
+        level: currentLevel,
+        title: subSchema.title,
+        description: subSchema.description,
+        isLastInGroup: true,
+        hasChildren: false,
+        containerType: null,
+        continuingLevels: [...continuingLevels],
+        options: processOptions(
+          choices,
+          currentLevel,
+          currentPath,
+          false,
+          subSchema.required || requiredFromParent,
+          continuingLevels,
+        ),
+      });
+    } else if (!subSchema.properties && subSchema.type) {
+      // This handles a schema that is just a single primitive type
+      flatRows.push({
+        type: 'property',
+        name: subSchema.title || '<value>',
+        path: currentPath,
+        level: currentLevel,
+        required: false,
+        propertyType: subSchema.type,
+        description: subSchema.description,
+        example: subSchema.examples || subSchema.example,
+        constraints: getConstraints(subSchema),
+        isLastInGroup: true,
+        hasChildren: false,
+        containerType: null,
+        continuingLevels: [...continuingLevels],
+      });
+    }
+  }
+
+  buildRows(schema, level, path, schema.required, parentContinuingLevels);
+  return flatRows;
+}

package/helpers/update-schema-ids.js

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import path from 'path';
+
+export default function updateSchemaIds(siteDir, url, version = null) {
+  const versionsJsonPath = path.join(siteDir, 'versions.json');
+  if (!fs.existsSync(versionsJsonPath)) {
+    console.log('No versions.json file found, skipping schema ID update.');
+    return;
+  }
+
+  const getAllFiles = (dir, allFiles = []) => {
+    const files = fs.readdirSync(dir);
+
+    files.forEach((file) => {
+      const filePath = path.join(dir, file);
+      if (fs.statSync(filePath).isDirectory()) {
+        getAllFiles(filePath, allFiles);
+      } else {
+        if (file.endsWith('.json')) {
+          allFiles.push(filePath);
+        }
+      }
+    });
+    return allFiles;
+  };
+
+  const versions = version
+    ? [version]
+    : JSON.parse(fs.readFileSync(versionsJsonPath, 'utf8'));
+
+  for (const version of versions) {
+    const schemaDir = path.join(siteDir, 'static/schemas', version);
+    if (!fs.existsSync(schemaDir)) {
+      continue;
+    }
+    const files = getAllFiles(schemaDir);
+
+    for (const file of files) {
+      const schema = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const baseUrl = url.endsWith('/') ? url.slice(0, -1) : url;
+      const relativePath = path.relative(path.join(siteDir, 'static'), file);
+      schema.$id = `${baseUrl}/${relativePath.replace(/\\/g, '/')}`;
+      fs.writeFileSync(file, JSON.stringify(schema, null, 2));
+      console.log(`Updated $id for ${file} in version ${version}`);
+    }
+  }
+}