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

package/helpers/getConstraints.js

@@ -0,0 +1,53 @@
+// 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}`,
+
+    // 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');
+    }
+
+    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;
+};

package/helpers/loadSchema.js

@@ -0,0 +1,11 @@
+import fs from 'fs';
+
+/**
+ * Loads a JSON schema file and returns its content as a JSON object.
+ * @param {string} filePath Path to the JSON schema file.
+ * @returns {object} The parsed JSON schema.
+ */
+export default function loadSchema(filePath) {
+    const rawContent = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(rawContent);
+}

package/helpers/mdx-template.js

@@ -0,0 +1,36 @@
+export default function MdxTemplate(data) {
+    const {
+        schema,
+        mergedSchema,
+        baseEditUrl,
+        file,
+        topPartialImport,
+        bottomPartialImport,
+        topPartialComponent,
+        bottomPartialComponent
+    } = data;
+
+    return `---
+title: ${schema.title}
+description: ${JSON.stringify(schema.description)}
+sidebar_label: ${schema.title}
+custom_edit_url: ${baseEditUrl}/demo/static/schemas/${file}
+---
+
+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/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/index.js

@@ -1,17 +1,31 @@
 import validateSchemas from './validateSchemas.js';
 import generateEventDocs from './generateEventDocs.js';
 import path from 'path';
-import { fileURLToPath } from 'url';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+export default async function (context) {
+    const { siteDir } = context;
+    const { organizationName, projectName } = context.siteConfig;
+    const options = { organizationName, projectName, siteDir };
+    const schemasPath = path.join(siteDir, 'static/schemas');
+
+    // Generate docs on startup
+    await generateEventDocs(options);
 
-export default function (context, options) {
     return {
         name: 'docusaurus-plugin-generate-schema-docs',
 
+        getPathsToWatch() {
+            // Watch the schemas directory for changes
+            return [schemasPath];
+        },
+
+        async loadContent() {
+            // Generate event documentation when watched files change
+            await generateEventDocs(options);
+        },
+
         getThemePath() {
-            return path.resolve(__dirname, './components');
+            return './components';
         },
 
         extendCli(cli) {
@@ -21,7 +35,7 @@ export default function (context, options) {
                 .action(async () => {
                     console.log('Validating GTM Schemas...');
                     // You might get the path from 'options' or assume a default
-                    const schemaPath = options?.path || path.join(context.siteDir, 'schemas');
+                    const schemaPath = options?.path || path.join(context.siteDir, 'static/schemas');
 
                     const success = await validateSchemas(schemaPath);
 
@@ -42,9 +56,5 @@ export default function (context, options) {
                     await generateEventDocs();
                 });
         },
-
-        async loadContent() {
-            await generateEventDocs();
-        },
     };
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-generate-schema-docs",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Docusaurus plugin to generate documentation from JSON schemas.",
   "main": "index.js",
   "license": "MIT",
@@ -10,11 +10,14 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.1.3",
-    "fs-extra": "^11.2.0",
+    "fs-extra": "^11.3.3",
     "json-schema-merge-allof": "^0.8.1"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
   }
-}
+}

package/validateSchemas.js

@@ -2,11 +2,13 @@ import fs from 'fs';
 import path from 'path';
 import buildExampleFromSchema from './helpers/buildExampleFromSchema';
 import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
 import $RefParser from "@apidevtools/json-schema-ref-parser";
 import mergeJsonSchema from "json-schema-merge-allof";
 
 const validateSchemas = async (schemaPath) => {
     const ajv = new Ajv2020();
+    addFormats(ajv);
     ajv.addKeyword('x-gtm-clear');
 
     const getAllFiles = (dir, allFiles = []) => {
@@ -28,7 +30,7 @@ const validateSchemas = async (schemaPath) => {
         return allFiles;
     };
 
-    const allSchemaFiles = getAllFiles('schemas');
+    const allSchemaFiles = getAllFiles(schemaPath);
     for (const file of allSchemaFiles)
     {
         const schemaContent = fs.readFileSync(file, 'utf-8');
@@ -41,7 +43,7 @@ const validateSchemas = async (schemaPath) => {
     for (const file of schemaFiles)
     {
         const filePath = path.join(schemaPath, file);
-        
+
         // Dereference and merge, same as in generateEventDocs.js
         const clonedSchema = await $RefParser.dereference(filePath, {
             mutateInputSchema: false, dereference: {
@@ -64,7 +66,8 @@ const validateSchemas = async (schemaPath) => {
         {
             const originalSchema = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
             const validate = ajv.getSchema(originalSchema.$id);
-            if (!validate) {
+            if (!validate)
+            {
                 console.error(`❌ Could not find compiled schema for ${originalSchema.$id}`);
                 allValid = false;
                 continue;