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

package/helpers/buildExampleFromSchema.js

@@ -1,83 +1,69 @@
+/**
+ * Recursively builds a single, default example object from a JSON schema.
+ * It prefers explicit examples, consts, or defaults. For choices (`oneOf`/`anyOf`),
+ * it defaults to the first option.
+ *
+ * @param {object} schema The schema to build an example from.
+ * @returns {object|undefined} The generated example.
+ */
 const buildExampleFromSchema = (schema) => {
-    const buildValue = (prop) => {
-        if (!prop) return undefined;
+  if (!schema) return undefined;
 
-        // 1. Prefer explicit examples or constants if available
-        if (prop.examples && prop.examples.length) return prop.examples[0];
-        if (prop.const !== undefined) return prop.const;
-        if (prop.default !== undefined) return prop.default;
+  // For choices, default to the first option.
+  if (schema.oneOf?.length > 0) {
+    return buildExampleFromSchema(schema.oneOf[0]);
+  }
+  if (schema.anyOf?.length > 0) {
+    return buildExampleFromSchema(schema.anyOf[0]);
+  }
 
-        const type = Array.isArray(prop.type) ? prop.type[0] : prop.type;
+  // Prefer const, explicit examples, or default values.
+  if (typeof schema.const !== 'undefined') return schema.const;
+  if (schema.examples?.length > 0) return schema.examples[0];
+  if (typeof schema.default !== 'undefined') return schema.default;
 
-        if (type === 'object')
-        {
-            if (prop.properties)
-            {
-                const obj = {};
-                Object.entries(prop.properties).forEach(([k, v]) => {
-                    const val = buildValue(v);
-                    // Only add the property if it has a valid value (not undefined)
-                    if (val !== undefined)
-                    {
-                        obj[k] = val;
-                    }
-                });
+  let type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  if (!type && schema.properties) {
+    type = 'object';
+  }
 
-                // If the object ends up having no keys, consider it "empty" and return undefined
-                if (Object.keys(obj).length === 0) return undefined;
-                return obj;
-            }
-            // Object with no properties defined
-            return undefined;
+  if (type === 'object') {
+    if (schema.properties) {
+      const obj = {};
+      Object.entries(schema.properties).forEach(([key, propSchema]) => {
+        const value = buildExampleFromSchema(propSchema);
+        if (typeof value !== 'undefined') {
+          obj[key] = value;
         }
-
-        if (type === 'array')
-        {
-            if (prop.items)
-            {
-                const itemVal = buildValue(prop.items);
-                // If the inner item is valid, return it as an array
-                if (itemVal !== undefined)
-                {
-                    return [itemVal];
-                }
-            }
-            // Empty array or array of undefined items
-            return undefined;
-        }
-
-        switch (type)
-        {
-            case 'string': return '';
-            case 'integer':
-            case 'number': return 0;
-            case 'boolean': return false;
-            default: return undefined;
-        }
-    };
-
-    // If the schema provides a top-level examples array with an object, prefer it
-    if (schema && schema.examples && schema.examples.length)
-    {
-        const first = schema.examples[0];
-        if (typeof first === 'object' && first !== null) return first;
+      });
+      // Return undefined for objects that end up empty.
+      return Object.keys(obj).length > 0 ? obj : undefined;
     }
+    // No properties defined, treat as an empty object (which we filter out).
+    return undefined;
+  }
 
-    // Otherwise, build from properties
-    if (schema && schema.properties)
-    {
-        const out = {};
-        Object.entries(schema.properties).forEach(([k, p]) => {
-            const val = buildValue(p);
-            // Only add top-level keys if they are not undefined
-            if (val !== undefined)
-            {
-                out[k] = val;
-            }
-        });
-        return out;
+  if (type === 'array') {
+    if (schema.items) {
+      const itemValue = buildExampleFromSchema(schema.items);
+      // Only return an array if the item schema generates a value.
+      return typeof itemValue !== 'undefined' ? [itemValue] : undefined;
     }
+    return undefined; // No items defined.
+  }
+
+  // Return placeholder values for primitive types if no other value is found.
+  switch (type) {
+    case 'string':
+      return '';
+    case 'integer':
+    case 'number':
+      return 0;
+    case 'boolean':
+      return false;
+    default:
+      return undefined;
+  }
+};
 
-    return {};
-}
 export default buildExampleFromSchema;

package/helpers/choice-index-template.js

@@ -0,0 +1,22 @@
+export default function ChoiceIndexTemplate(data) {
+  const { schema, processedOptions } = data;
+
+  return `---
+title: ${schema.title}
+description: "${schema.description}"
+---
+import SchemaJsonViewer from '@theme/SchemaJsonViewer';
+
+# ${schema.title}
+
+${schema.description}
+
+Please select one of the following options:
+
+${processedOptions
+  .map((option) => `- [${option.schema.title}](./${option.slug})`)
+  .join('\n')}
+
+<SchemaJsonViewer schema={${JSON.stringify(schema)}} />
+`;
+}

package/helpers/file-system.js

@@ -0,0 +1,32 @@
+import fs from 'fs';
+import path from 'path';
+import loadSchema from './loadSchema';
+
+export function createDir(directory) {
+  if (!fs.existsSync(directory)) {
+    fs.mkdirSync(directory, { recursive: true });
+  }
+}
+
+export function readSchemas(directory) {
+  const files = fs
+    .readdirSync(directory)
+    .filter((file) => file.endsWith('.json'));
+
+  return files.map((file) => {
+    const filePath = path.join(directory, file);
+    const schema = loadSchema(filePath);
+    return {
+      fileName: file,
+      filePath,
+      schema,
+    };
+  });
+}
+
+export function writeDoc(outputDir, fileName, content) {
+  fs.writeFileSync(path.join(outputDir, fileName), content);
+  console.log(
+    `✅ Generated ${path.relative(process.cwd(), path.join(outputDir, fileName))}`,
+  );
+}

package/helpers/getConstraints.js

@@ -1,53 +1,52 @@
 // A list of JSON Schema keywords that have simple key-value constraints.
 const constraintHandlers = {
-    // Simple key-value constraints
-    minLength: (val) => `minLength: ${val}`,
-    maxLength: (val) => `maxLength: ${val}`,
-    minimum: (val) => `minimum: ${val}`,
-    maximum: (val) => `maximum: ${val}`,
-    exclusiveMinimum: (val) => `exclusiveMinimum: ${val}`,
-    exclusiveMaximum: (val) => `exclusiveMaximum: ${val}`,
-    minItems: (val) => `minItems: ${val}`,
-    maxItems: (val) => `maxItems: ${val}`,
-    minProperties: (val) => `minProperties: ${val}`,
-    maxProperties: (val) => `maxProperties: ${val}`,
-    multipleOf: (val) => `multipleOf: ${val}`,
-    format: (val) => `format: ${val}`,
-    minContains: (val) => `minContains: ${val}`,
-    maxContains: (val) => `maxContains: ${val}`,
+  // Simple key-value constraints
+  minLength: (val) => `minLength: ${val}`,
+  maxLength: (val) => `maxLength: ${val}`,
+  minimum: (val) => `minimum: ${val}`,
+  maximum: (val) => `maximum: ${val}`,
+  exclusiveMinimum: (val) => `exclusiveMinimum: ${val}`,
+  exclusiveMaximum: (val) => `exclusiveMaximum: ${val}`,
+  minItems: (val) => `minItems: ${val}`,
+  maxItems: (val) => `maxItems: ${val}`,
+  minProperties: (val) => `minProperties: ${val}`,
+  maxProperties: (val) => `maxProperties: ${val}`,
+  multipleOf: (val) => `multipleOf: ${val}`,
+  format: (val) => `format: ${val}`,
+  minContains: (val) => `minContains: ${val}`,
+  maxContains: (val) => `maxContains: ${val}`,
 
-    // Special-cased constraints
-    pattern: (val) => `pattern: /${val}/`,
-    uniqueItems: (val) => (val ? 'uniqueItems: true' : null),
-    additionalProperties: (val) => (val === false ? 'additionalProperties: false' : null),
-    propertyNames: (val) => `propertyNames: ${JSON.stringify(val)}`,
-    dependentRequired: (val) => {
-        const deps = Object.entries(val).map(([key, depVal]) => `${key} -> [${depVal.join(', ')}]`).join('; ');
-        return `dependentRequired: ${deps}`;
-    },
-    contains: (val) => `contains: ${JSON.stringify(val)}`,
-    enum: (val) => `enum: [${val.join(', ')}]`,
-    const: (val) => `const: ${JSON.stringify(val)}`,
+  // Special-cased constraints
+  pattern: (val) => `pattern: /${val}/`,
+  uniqueItems: (val) => (val ? 'uniqueItems: true' : null),
+  additionalProperties: (val) =>
+    val === false ? 'additionalProperties: false' : null,
+  propertyNames: (val) => `propertyNames: ${JSON.stringify(val)}`,
+  dependentRequired: (val) => {
+    const deps = Object.entries(val)
+      .map(([key, depVal]) => `${key} -> [${depVal.join(', ')}]`)
+      .join('; ');
+    return `dependentRequired: ${deps}`;
+  },
+  contains: (val) => `contains: ${JSON.stringify(val)}`,
+  enum: (val) => `enum: [${val.join(', ')}]`,
+  const: (val) => `const: ${JSON.stringify(val)}`,
 };
 
 export const getConstraints = (prop, isReq) => {
-    const constraints = [];
-    if (isReq)
-    {
-        constraints.push('required');
-    }
+  const constraints = [];
+  if (isReq) {
+    constraints.push('required');
+  }
 
-    for (const keyword in constraintHandlers)
-    {
-        if (prop[keyword] !== undefined)
-        {
-            const handler = constraintHandlers[keyword];
-            const result = handler(prop[keyword]);
-            if (result)
-            {
-                constraints.push(result);
-            }
-        }
+  for (const keyword in constraintHandlers) {
+    if (prop[keyword] !== undefined) {
+      const handler = constraintHandlers[keyword];
+      const result = handler(prop[keyword]);
+      if (result) {
+        constraints.push(result);
+      }
     }
-    return constraints;
+  }
+  return constraints;
 };

package/helpers/loadSchema.js

@@ -6,6 +6,6 @@ import fs from 'fs';
  * @returns {object} The parsed JSON schema.
  */
 export default function loadSchema(filePath) {
-    const rawContent = fs.readFileSync(filePath, 'utf-8');
-    return JSON.parse(rawContent);
+  const rawContent = fs.readFileSync(filePath, 'utf-8');
+  return JSON.parse(rawContent);
 }

package/helpers/path-helpers.js

@@ -0,0 +1,22 @@
+import path from 'path';
+
+export function getPathsForVersion(version, siteDir) {
+  let schemaDir;
+  let outputDir;
+
+  if (version) {
+    if (version !== 'current') {
+      schemaDir = path.join(siteDir, 'static/schemas', version);
+      outputDir = path.join(siteDir, 'versioned_docs', `version-${version}`);
+    } else {
+      schemaDir = path.join(siteDir, 'static/schemas', 'next');
+      outputDir = path.join(siteDir, 'docs');
+    }
+  } else {
+    // Non-versioned
+    schemaDir = path.join(siteDir, 'static/schemas');
+    outputDir = path.join(siteDir, 'docs');
+  }
+
+  return { schemaDir, outputDir };
+}

package/helpers/processSchema.js

@@ -1,5 +1,5 @@
-import $RefParser from "@apidevtools/json-schema-ref-parser";
-import mergeJsonSchema from "json-schema-merge-allof";
+import $RefParser from '@apidevtools/json-schema-ref-parser';
+import mergeJsonSchema from 'json-schema-merge-allof';
 
 /**
  * Processes a JSON schema file by bundling external references,
@@ -9,24 +9,24 @@ import mergeJsonSchema from "json-schema-merge-allof";
  * @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,
-    });
+  // 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
-        }
-    });
+  // 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
-        }
-    });
+  // Then merge allOf properties
+  const mergedSchema = mergeJsonSchema(dereferencedSchema, {
+    resolvers: {
+      defaultResolver: mergeJsonSchema.options.resolvers.title,
+    },
+  });
 
-    return mergedSchema;
+  return mergedSchema;
 }

package/helpers/{mdx-template.js → schema-doc-template.js}

@@ -1,20 +1,20 @@
 export default function MdxTemplate(data) {
-    const {
-        schema,
-        mergedSchema,
-        baseEditUrl,
-        file,
-        topPartialImport,
-        bottomPartialImport,
-        topPartialComponent,
-        bottomPartialComponent
-    } = data;
+  const {
+    schema,
+    mergedSchema,
+    editUrl,
+    file,
+    topPartialImport,
+    bottomPartialImport,
+    topPartialComponent,
+    bottomPartialComponent,
+  } = data;
 
-    return `---
+  return `---
 title: ${schema.title}
 description: ${JSON.stringify(schema.description)}
 sidebar_label: ${schema.title}
-custom_edit_url: ${baseEditUrl}/demo/static/schemas/${file}
+custom_edit_url: ${editUrl}
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';

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,
+    };
+  });
+}