docusaurus-plugin-generate-schema-docs 1.4.0 → 1.5.0

package/__tests__/helpers/validator.test.js

@@ -0,0 +1,115 @@
+import { createValidator } from '../../helpers/validator';
+
+describe('createValidator', () => {
+  it('creates a validator that returns true for valid data with no schema version (draft-07)', async () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+        },
+      },
+      required: ['name'],
+    };
+
+    const validator = await createValidator(schema);
+    const result = validator({ name: 'test' });
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('creates a validator that returns false for invalid data with no schema version (draft-07)', async () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+        },
+      },
+      required: ['name'],
+    };
+
+    const validator = await createValidator(schema);
+    const result = validator({ name: 123 });
+
+    expect(result.valid).toBe(false);
+    expect(result.errors).not.toEqual([]);
+  });
+
+  it('creates a validator that can validate against a draft-04 schema', async () => {
+    const schema = {
+      $schema: 'http://json-schema.org/draft-04/schema#',
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+        },
+      },
+      required: ['name'],
+    };
+
+    const validator = await createValidator(schema);
+    const result = validator({ name: 'test' });
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('creates a validator that can validate against a draft-07 schema', async () => {
+    const schema = {
+      $schema: 'http://json-schema.org/draft-07/schema#',
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+        },
+      },
+      required: ['name'],
+    };
+
+    const validator = await createValidator(schema);
+    const result = validator({ name: 'test' });
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('creates a validator that can validate against a 2019-09 schema', async () => {
+    const schema = {
+      $schema: 'https://json-schema.org/draft/2019-09/schema',
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+        },
+      },
+      required: ['name'],
+    };
+
+    const validator = await createValidator(schema);
+    const result = validator({ name: 'test' });
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('creates a validator that can validate against a 2020-12 schema', async () => {
+    const schema = {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+        },
+      },
+      required: ['name'],
+    };
+
+    const validator = await createValidator(schema);
+    const result = validator({ name: 'test' });
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+});

package/__tests__/validateSchemas-integration.test.js

@@ -0,0 +1,29 @@
+/**
+ * @jest-environment node
+ */
+
+import path from 'path';
+import validateSchemas from '../validateSchemas';
+import { getPathsForVersion } from '../helpers/path-helpers';
+
+describe('validateSchemas - Integration', () => {
+  let consoleErrorSpy;
+  let consoleLogSpy;
+
+  beforeEach(() => {
+    // Spy on console.error and console.log to keep test output clean
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    consoleLogSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('should return true for the "next" version schemas', async () => {
+    const siteDir = path.resolve(__dirname, '../../../demo');
+    const { schemaDir } = getPathsForVersion('next', siteDir);
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(true);
+  });
+});

package/__tests__/validateSchemas.test.js

@@ -14,124 +14,40 @@ describe('validateSchemas', () => {
 
   beforeEach(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'schema-test-'));
-    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
-    consoleLogSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
   });
 
   afterEach(() => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
-    jest.restoreAllMocks();
   });
 
-  const writeSchema = (dir, fileName, content) => {
-    const filePath = path.join(dir, fileName);
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, JSON.stringify(content, null, 2));
-  };
-
-  const loadFixture = (fixtureName) => {
-    const fixturePath = path.resolve(
+  it('should return true for a complex set of valid schemas', async () => {
+    const fixtureDir = path.resolve(
       __dirname,
       '__fixtures__',
       'validateSchemas',
-      fixtureName,
+      'complex-validation',
     );
-    const schemaContent = fs.readFileSync(fixturePath, 'utf8');
-    return JSON.parse(schemaContent);
-  };
-
-  it('should return true when all schemas are valid', async () => {
-    const validSchema = loadFixture('valid-schema.json');
-    writeSchema(tmpDir, 'valid-schema.json', validSchema);
-
-    const result = await validateSchemas(tmpDir);
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+    fs.cpSync(fixtureDir, schemaDir, { recursive: true });
+    const result = await validateSchemas(schemaDir);
     expect(result).toBe(true);
-    expect(consoleLogSpy).toHaveBeenCalledWith(
-      'OK Schema valid-schema.json produced a valid example.',
-    );
   });
 
   it('should return false if an example fails validation', async () => {
-    const invalidExampleSchema = loadFixture('invalid-example-schema.json');
-    writeSchema(tmpDir, 'invalid-example-schema.json', invalidExampleSchema);
-
-    const result = await validateSchemas(tmpDir);
-    expect(result).toBe(false);
-    expect(consoleErrorSpy).toHaveBeenCalledWith(
-      'x Schema invalid-example-schema.json example data failed validation:',
+    const fixturePath = path.resolve(
+      __dirname,
+      '__fixtures__',
+      'validateSchemas',
+      'invalid-example-schema.json',
     );
-    expect(consoleErrorSpy).toHaveBeenCalledWith(
-      expect.arrayContaining([
-        expect.objectContaining({
-          instancePath: '/age',
-          keyword: 'type',
-          message: 'must be number',
-        }),
-      ]),
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+    fs.copyFileSync(
+      fixturePath,
+      path.join(schemaDir, 'invalid-example-schema.json'),
     );
-  });
-
-  it('should fail validation for missing required property', async () => {
-    const noValidExampleSchema = loadFixture('no-example-schema.json');
-    writeSchema(tmpDir, 'no-valid-example-schema.json', noValidExampleSchema);
-
-    const result = await validateSchemas(tmpDir);
+    const result = await validateSchemas(schemaDir);
     expect(result).toBe(false);
-    expect(consoleErrorSpy).toHaveBeenCalledWith(
-      'x Schema no-valid-example-schema.json does not produce a valid example.',
-    );
-  });
-
-  it('should handle schemas with $refs correctly', async () => {
-    const componentSchema = loadFixture(
-      path.join('components', 'referenced.json'),
-    );
-    const mainSchema = loadFixture('main-schema-with-ref.json');
-
-    writeSchema(
-      path.join(tmpDir, 'components'),
-      'referenced.json',
-      componentSchema,
-    );
-    writeSchema(tmpDir, 'main-schema-with-ref.json', mainSchema);
-
-    const result = await validateSchemas(tmpDir);
-    expect(result).toBe(true);
-    expect(consoleLogSpy).toHaveBeenCalledWith(
-      'OK Schema main-schema-with-ref.json produced a valid example.',
-    );
-  });
-
-  it('should reject if a referenced schema is missing', async () => {
-    const mainSchema = loadFixture('main-schema-with-missing-ref.json');
-    writeSchema(tmpDir, 'main-schema-with-missing-ref.json', mainSchema);
-
-    const expectedErrorPath = path.join(tmpDir, 'non-existent-component.json');
-    await expect(validateSchemas(tmpDir)).rejects.toThrow(
-      expect.objectContaining({
-        message: expect.stringContaining(
-          `Error opening file ${expectedErrorPath}`,
-        ),
-      }),
-    );
-  });
-
-  it('should throw an error if duplicate schema IDs are found', async () => {
-    const schemaA = {
-      $id: 'duplicate-id',
-      type: 'object',
-      properties: { a: { type: 'string' } },
-    };
-    const schemaB = {
-      $id: 'duplicate-id',
-      type: 'object',
-      properties: { b: { type: 'string' } },
-    };
-    writeSchema(path.join(tmpDir, 'A'), 'schema-A.json', schemaA);
-    writeSchema(path.join(tmpDir, 'B'), 'schema-B.json', schemaB);
-
-    await expect(validateSchemas(tmpDir)).rejects.toThrow(
-      'schema with key or id "duplicate-id" already exists',
-    );
   });
 });

package/helpers/buildExampleFromSchema.js

@@ -1,71 +1,66 @@
 import { getSingleExampleValue } from './example-helper';
+import mergeJsonSchema from 'json-schema-merge-allof';
 
-/**
- * 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) => {
-  if (!schema) return undefined;
+const getPrimitivePlaceholder = (type) => {
+  switch (type) {
+    case 'string':
+      return '';
+    case 'integer':
+    case 'number':
+      return 0;
+    case 'boolean':
+      return false;
+    default:
+      return undefined;
+  }
+};
 
-  // For choices, default to the first option.
-  if (schema.oneOf?.length > 0) {
-    return buildExampleFromSchema(schema.oneOf[0]);
+const buildExampleFromSchema = (schema) => {
+  if (!schema) {
+    return undefined;
   }
-  if (schema.anyOf?.length > 0) {
-    return buildExampleFromSchema(schema.anyOf[0]);
+
+  // For choices, default to the first option and recurse.
+  const choiceType = schema.oneOf ? 'oneOf' : schema.anyOf ? 'anyOf' : null;
+  if (choiceType && schema[choiceType]?.length > 0) {
+    const newSchema = { ...schema };
+    const choice = newSchema[choiceType][0];
+    delete newSchema[choiceType];
+    const merged = mergeJsonSchema({ allOf: [newSchema, choice] });
+    return buildExampleFromSchema(merged);
   }
 
+  // If there's an explicit example, use it.
   const exampleValue = getSingleExampleValue(schema);
   if (typeof exampleValue !== 'undefined') {
     return exampleValue;
   }
 
-  let type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
-  if (!type && schema.properties) {
-    type = 'object';
-  }
+  // Determine the type, defaulting to 'object' if properties are present.
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  const inferredType = !type && schema.properties ? 'object' : type;
 
-  if (type === 'object') {
-    if (schema.properties) {
-      const obj = {};
-      Object.entries(schema.properties).forEach(([key, propSchema]) => {
+  // Build examples based on type.
+  if (inferredType === 'object' && schema.properties) {
+    const obj = Object.entries(schema.properties).reduce(
+      (acc, [key, propSchema]) => {
         const value = buildExampleFromSchema(propSchema);
         if (typeof value !== 'undefined') {
-          obj[key] = value;
+          acc[key] = value;
         }
-      });
-      // 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;
+        return acc;
+      },
+      {},
+    );
+    return Object.keys(obj).length > 0 ? obj : undefined;
   }
 
-  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.
+  if (inferredType === 'array' && schema.items) {
+    const itemValue = buildExampleFromSchema(schema.items);
+    return typeof itemValue !== 'undefined' ? [itemValue] : undefined;
   }
 
-  // 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 getPrimitivePlaceholder(inferredType);
 };
 
 export default buildExampleFromSchema;

package/helpers/file-system.js

@@ -1,6 +1,5 @@
 import fs from 'fs';
 import path from 'path';
-import loadSchema from './loadSchema';
 
 export function createDir(directory) {
   if (!fs.existsSync(directory)) {
@@ -15,7 +14,7 @@ export function readSchemas(directory) {
 
   return files.map((file) => {
     const filePath = path.join(directory, file);
-    const schema = loadSchema(filePath);
+    const schema = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
     return {
       fileName: file,
       filePath,

package/helpers/schema-processing.js

@@ -15,21 +15,6 @@ export function slugify(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;

package/helpers/schemaToExamples.js

@@ -1,99 +1,71 @@
 import buildExampleFromSchema from './buildExampleFromSchema';
+import mergeJsonSchema from 'json-schema-merge-allof';
 
-/**
- * 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 = [];
+const findChoicePoints = (subSchema, path = []) => {
+  if (!subSchema) {
+    return [];
+  }
 
-  // 1. Find all choice points in the schema recursively
-  function findChoices(subSchema, path = []) {
-    if (!subSchema) return;
+  const choiceType = subSchema.oneOf
+    ? 'oneOf'
+    : subSchema.anyOf
+      ? 'anyOf'
+      : null;
+  const currentChoice = choiceType ? [{ path, schema: subSchema }] : [];
 
-    // 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 });
-    }
+  const nestedChoices = subSchema.properties
+    ? Object.entries(subSchema.properties).flatMap(([key, propSchema]) =>
+        findChoicePoints(propSchema, [...path, 'properties', key]),
+      )
+    : [];
+
+  return [...currentChoice, ...nestedChoices];
+};
+
+const generateExampleForChoice = (rootSchema, path, option) => {
+  const schemaVariant = JSON.parse(JSON.stringify(rootSchema));
 
-    // Then, recurse into any nested properties
-    if (subSchema.properties) {
-      for (const [key, propSchema] of Object.entries(subSchema.properties)) {
-        findChoices(propSchema, [...path, 'properties', key]);
-      }
+  if (path.length === 0) {
+    delete schemaVariant.oneOf;
+    delete schemaVariant.anyOf;
+    const newSchemaVariant = mergeJsonSchema({
+      allOf: [schemaVariant, option],
+    });
+    return buildExampleFromSchema(newSchemaVariant);
+  } else {
+    let parentOfChoice = schemaVariant;
+    for (let i = 0; i < path.length; i++) {
+      parentOfChoice = parentOfChoice[path[i]];
     }
+    delete parentOfChoice.oneOf;
+    delete parentOfChoice.anyOf;
+    Object.assign(parentOfChoice, option);
+    return buildExampleFromSchema(schemaVariant);
   }
+};
 
-  findChoices(rootSchema);
+export function schemaToExamples(rootSchema) {
+  const choicePoints = findChoicePoints(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 }],
-        },
+        { 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,
-      };
-    });
+    const options = schema[choiceType].map((option) => ({
+      title: option.title || 'Option',
+      example: generateExampleForChoice(rootSchema, path, option),
+    }));
 
-    return {
-      property: propertyName,
-      options,
-    };
+    return { property: propertyName, options };
   });
 }