refactor: schema generation to be less coupled to comment-json (#262)

* feat: add shouldBeGenerated to metaData * refactor: remove recursion comments * refactor: generate metaData for all schemas for all refHandling modes * refactor: abstract stringify function * chore: add changeset
toomuchdesign · May 25, 2024 · e63f47e · e63f47e
1 parent e6f83b0
commit e63f47e
Show file tree

Hide file tree

Showing 15 changed files with 127 additions and 87 deletions.
diff --git a/.changeset/healthy-panthers-speak.md b/.changeset/healthy-panthers-speak.md
@@ -0,0 +1,5 @@
+---
+'openapi-ts-json-schema': minor
+---
+
+`shouldBeGenerated` prop added to `metaData`
diff --git a/.changeset/mighty-pans-dress.md b/.changeset/mighty-pans-dress.md
@@ -0,0 +1,5 @@
+---
+'openapi-ts-json-schema': minor
+---
+
+Recursion comments removed
diff --git a/README.md b/README.md
@@ -136,6 +136,8 @@ Beside generating the expected schema files under `outputPath`, `openapiToTsJson
         // Original dereferenced JSON schema
         isRef: boolean;
         // True if schemas is used as a `$ref`
+        shouldBeGenerated: boolean;
+        // True is the schema has to be generated
 
         absoluteDirName: string;
         // Absolute path pointing to schema folder (posix or win32). Eg: `"Users/username/output/path/components/schemas"`

diff --git a/src/openapiToTsJsonSchema.ts b/src/openapiToTsJsonSchema.ts
@@ -140,25 +140,6 @@ export async function openapiToTsJsonSchema(
   const jsonSchema = convertOpenApiPathsParameters(dereferencedJsonSchema);
   const schemaMetaDataMap: SchemaMetaDataMap = new Map();
 
-  /**
-   * Create meta data for $ref schemas which have been previously dereferenced.
-   * It happens only with "import" and "keep" refHandling since they expect
-   * $ref schemas to be generated no matter of
-   */
-  if (refHandling === 'import' || refHandling === 'keep') {
-    for (const [id, { openApiDefinition, jsonSchema }] of inlinedRefs) {
-      addSchemaToMetaData({
-        id,
-        $id: $idMapper({ id }),
-        schemaMetaDataMap,
-        openApiDefinition,
-        jsonSchema,
-        outputPath,
-        isRef: true,
-      });
-    }
-  }
-
   /**
    * Create meta data for each output schema
    */
@@ -180,10 +161,38 @@ export async function openapiToTsJsonSchema(
         jsonSchema: jsonSchemaDefinitions[schemaName],
         outputPath,
         isRef: inlinedRefs.has(id),
+        shouldBeGenerated: true,
       });
     }
   }
 
+  /**
+   * Create meta data for each $ref schemas which have been previously dereferenced.
+   */
+  for (const [id, { openApiDefinition, jsonSchema }] of inlinedRefs) {
+    /**
+     * In "inline" mode $ref schemas not explicitly marked for generation
+     * should not be generated
+     *
+     * All the other "refHandling" modes generate all $ref schemas
+     */
+    let shouldBeGenerated = true;
+    if (refHandling === 'inline' && !schemaMetaDataMap.has(id)) {
+      shouldBeGenerated = false;
+    }
+
+    addSchemaToMetaData({
+      id,
+      $id: $idMapper({ id }),
+      schemaMetaDataMap,
+      openApiDefinition,
+      jsonSchema,
+      outputPath,
+      isRef: true,
+      shouldBeGenerated,
+    });
+  }
+
   const returnPayload: ReturnPayload = {
     outputPath,
     metaData: { schemas: schemaMetaDataMap },

diff --git a/src/plugins/fastifyIntegrationPlugin.ts b/src/plugins/fastifyIntegrationPlugin.ts
@@ -22,7 +22,8 @@ const fastifyIntegrationPlugin: Plugin<PluginOptions | void> = ({
   onBeforeGeneration: async ({ outputPath, metaData, options, utils }) => {
     // Derive the schema data necessary to generate the declarations
     const allSchemas = [...metaData.schemas]
-      .map(([id, schema]) => schema)
+      .map(([_id, schema]) => schema)
+      .filter((schema) => schema.shouldBeGenerated)
       .map(({ absoluteImportPath, uniqueName, id, isRef }) => {
         return {
           importPath: utils.makeRelativeModulePath({

diff --git a/src/types.ts b/src/types.ts
@@ -65,6 +65,7 @@ export type Options = {
  * @property `id` - Internal unique schema identifier. Eg `"/components/schemas/MySchema"`
  * @property `$id` - JSON schema Compound Schema Document `$id`. Eg `"/components/schemas/MySchema"`
  * @property `isRef` - True if schemas is used as `$ref`
+ * @property `shouldBeGenerated` - True is the schema has to be generated
  * @property `uniqueName` - Unique JavaScript identifier used as import name. Eg: `"componentsSchemasMySchema"`
  * @property `openApiDefinition` - Original dereferenced openAPI definition
  * @property `originalSchema` - Original dereferenced JSON schema
@@ -77,6 +78,7 @@ export type SchemaMetaData = {
   id: string;
   $id: string;
   isRef: boolean;
+  shouldBeGenerated: boolean;
   uniqueName: string;
   openApiDefinition?: OpenApiObject;
   originalSchema: JSONSchema;

diff --git a/src/utils/addSchemaToMetaData.ts b/src/utils/addSchemaToMetaData.ts
@@ -24,6 +24,7 @@ export function addSchemaToMetaData({
   openApiDefinition,
   jsonSchema,
   isRef,
+  shouldBeGenerated,
   // Options
   outputPath,
 }: {
@@ -33,33 +34,32 @@ export function addSchemaToMetaData({
   openApiDefinition: OpenApiObject;
   jsonSchema: JSONSchema;
   isRef: boolean;
+  shouldBeGenerated: boolean;
   outputPath: string;
 }): void {
-  // Do not override existing meta info of inlined schemas
-  if (!schemaMetaDataMap.has(id)) {
-    const { schemaRelativeDirName, schemaName } = parseId(id);
-    const absoluteDirName = path.join(outputPath, schemaRelativeDirName);
-    const schemaFileName = filenamify(schemaName);
-    const absoluteImportPath = path.join(absoluteDirName, schemaFileName);
+  const { schemaRelativeDirName, schemaName } = parseId(id);
+  const absoluteDirName = path.join(outputPath, schemaRelativeDirName);
+  const schemaFileName = filenamify(schemaName);
+  const absoluteImportPath = path.join(absoluteDirName, schemaFileName);
 
-    // Convert components.parameters after convertOpenApiPathsParameters is called
-    if (isOpenApiParameterObject(openApiDefinition)) {
-      jsonSchema = convertOpenApiParameterToJsonSchema(openApiDefinition);
-    }
+  // Convert components.parameters after convertOpenApiPathsParameters is called
+  if (isOpenApiParameterObject(openApiDefinition)) {
+    jsonSchema = convertOpenApiParameterToJsonSchema(openApiDefinition);
+  }
 
-    const metaInfo: SchemaMetaData = {
-      id,
-      $id,
-      uniqueName: namify(id),
-      isRef,
-      openApiDefinition,
-      originalSchema: jsonSchema,
+  const metaInfo: SchemaMetaData = {
+    id,
+    $id,
+    uniqueName: namify(id),
+    isRef,
+    shouldBeGenerated,
+    openApiDefinition,
+    originalSchema: jsonSchema,
 
-      absoluteDirName,
-      absoluteImportPath,
-      absolutePath: absoluteImportPath + '.ts',
-    };
+    absoluteDirName,
+    absoluteImportPath,
+    absolutePath: absoluteImportPath + '.ts',
+  };
 
-    schemaMetaDataMap.set(id, metaInfo);
-  }
+  schemaMetaDataMap.set(id, metaInfo);
 }
diff --git a/src/utils/makeTsJsonSchema/index.ts b/src/utils/makeTsJsonSchema/index.ts
@@ -1,8 +1,7 @@
-import { stringify } from 'comment-json';
+import { stringify } from './stringify';
 import { replaceInlinedRefsWithStringPlaceholder } from './replaceInlinedRefsWithStringPlaceholder';
 import { replacePlaceholdersWithImportedSchemas } from './replacePlaceholdersWithImportedSchemas';
 import { replacePlaceholdersWithRefs } from './replacePlaceholdersWithRefs';
-import { makeCircularRefReplacer } from './makeCircularRefReplacer';
 import { patchJsonSchema } from './patchJsonSchema';
 import { formatTypeScript } from '../';
 import type {
@@ -48,11 +47,7 @@ export async function makeTsJsonSchema({
    * Stringifying schema with "comment-json" instead of JSON.stringify
    * to generate inline comments for "inline" refHandling
    */
-  const stringifiedSchema = stringify(
-    patchedSchema,
-    makeCircularRefReplacer(),
-    2,
-  );
+  const stringifiedSchema = stringify(patchedSchema);
 
   let tsSchema = `
     const schema = ${stringifiedSchema} as const;

diff --git a/...keTsJsonSchema/makeCircularRefReplacer.ts → src/utils/makeTsJsonSchema/stringify.ts b/...keTsJsonSchema/makeCircularRefReplacer.ts → src/utils/makeTsJsonSchema/stringify.ts
@@ -1,14 +1,11 @@
-import { getId } from './getId';
+import { stringify as commentJsonStringify } from 'comment-json';
 
 /**
  * JSON.stringify replacer
  * Replace circular references with {}
  * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cyclic_object_value#circular_references
  */
-export function makeCircularRefReplacer(): (
-  key: string,
-  value: unknown,
-) => unknown {
+function makeCircularRefReplacer(): (key: string, value: unknown) => unknown {
   const ancestors: unknown[] = [];
   return function (this: unknown, key: string, value: unknown) {
     if (typeof value !== 'object' || value === null) {
@@ -23,19 +20,16 @@ export function makeCircularRefReplacer(): (
 
     // @NOTE Should we make recursion depth configurable?
     if (ancestors.includes(value)) {
-      const id = getId(value);
-      return {
-        // Drop an inline comment about recursion interruption
-        [Symbol.for('before')]: [
-          {
-            type: 'LineComment',
-            value: ` Circular recursion interrupted. Schema id: "${id}"`,
-          },
-        ],
-      };
+      return {};
     }
 
     ancestors.push(value);
     return value;
   };
 }
+
+const circularReplacer = makeCircularRefReplacer();
+
+export function stringify(input: unknown): string {
+  return commentJsonStringify(input, circularReplacer, 2);
+}
diff --git a/src/utils/makeTsJsonSchemaFiles.ts b/src/utils/makeTsJsonSchemaFiles.ts
@@ -21,15 +21,17 @@ export async function makeTsJsonSchemaFiles({
   $idMapper: $idMapper;
 }) {
   for (const [_, metaData] of schemaMetaDataMap) {
-    const tsSchema = await makeTsJsonSchema({
-      metaData,
-      schemaMetaDataMap,
-      refHandling,
-      schemaPatcher,
-      $idMapper,
-    });
+    if (metaData.shouldBeGenerated) {
+      const tsSchema = await makeTsJsonSchema({
+        metaData,
+        schemaMetaDataMap,
+        refHandling,
+        schemaPatcher,
+        $idMapper,
+      });
 
-    const { absolutePath } = metaData;
-    await saveFile({ path: [absolutePath], data: tsSchema });
+      const { absolutePath } = metaData;
+      await saveFile({ path: [absolutePath], data: tsSchema });
+    }
   }
 }
diff --git a/test/circularReference.test.ts b/test/circularReference.test.ts
@@ -32,21 +32,33 @@ describe('Circular reference', () => {
               description: 'February description',
               type: 'object',
               properties: {
-                previousMonth: {},
+                previousMonth: {
+                  description: 'January description',
+                  properties: {},
+                  type: 'object',
+                },
               },
             },
             nextMonthTwo: {
               description: 'February description',
               type: 'object',
               properties: {
-                previousMonth: {},
+                previousMonth: {
+                  description: 'January description',
+                  properties: {},
+                  type: 'object',
+                },
               },
             },
             nextMonthThree: {
               description: 'February description',
               type: 'object',
               properties: {
-                previousMonth: {},
+                previousMonth: {
+                  description: 'January description',
+                  properties: {},
+                  type: 'object',
+                },
               },
             },
           },
@@ -67,13 +79,22 @@ describe('Circular reference', () => {
       type: "object",
       properties: {
         nextMonth: {
-          // Circular recursion interrupted. Schema id: "/components/schemas/February"
+          // $ref: "#/components/schemas/February"
+          description: "February description",
+          type: "object",
+          properties: {},
         },
         nextMonthTwo: {
-          // Circular recursion interrupted. Schema id: "/components/schemas/February"
+          // $ref: "#/components/schemas/February"
+          description: "February description",
+          type: "object",
+          properties: {},
         },
         nextMonthThree: {
-          // Circular recursion interrupted. Schema id: "/components/schemas/February"
+          // $ref: "#/components/schemas/February"
+          description: "February description",
+          type: "object",
+          properties: {},
         },
       },
     },`;

diff --git a/test/metaData.test.ts b/test/metaData.test.ts
@@ -41,6 +41,7 @@ describe('Returned "metaData"', async () => {
         type: ['string', 'null'],
       },
       isRef: true,
+      shouldBeGenerated: true,
 
       absoluteDirName: `${outputPath}/components/schemas`.replaceAll(
         '/',
@@ -97,6 +98,7 @@ describe('Returned "metaData"', async () => {
         type: 'object',
       },
       isRef: false,
+      shouldBeGenerated: true,
 
       absoluteDirName: `${outputPath}/components/schemas`.replaceAll(
         '/',

diff --git a/test/plugins/fastifyIntegrationPlugin/fastifyIntegrationPlugin.test.ts b/test/plugins/fastifyIntegrationPlugin/fastifyIntegrationPlugin.test.ts
@@ -25,25 +25,25 @@ describe('fastifyIntegration plugin', () => {
     // @TODO find a better way to assert against generated types
     const expectedAsText = await formatTypeScript(`
       // File autogenerated by "openapi-ts-json-schema". Do not edit :)
-      import { with$id as componentsSchemasAnswer } from "./components/schemas/Answer";
       import { with$id as componentsSchemasJanuary } from "./components/schemas/January";
       import { with$id as componentsSchemasFebruary } from "./components/schemas/February";
       import { with$id as componentsSchemasMarch } from "./components/schemas/March";
+      import { with$id as componentsSchemasAnswer } from "./components/schemas/Answer";
 
       // RefSchemas type: tuple of $ref schema types to enable json-schema-to-ts hydrate $refs via "references" option
       export type RefSchemas = [
-        typeof componentsSchemasAnswer,
         typeof componentsSchemasJanuary,
         typeof componentsSchemasFebruary,
         typeof componentsSchemasMarch,
+        typeof componentsSchemasAnswer,
       ];
 
       // schemas: array of JSON schemas to be registered with "fastify.addSchema"
       export const schemas = [
-        componentsSchemasAnswer,
         componentsSchemasJanuary,
         componentsSchemasFebruary,
         componentsSchemasMarch,
+        componentsSchemasAnswer,
       ]`);
 
     expect(actualAsText).toBe(expectedAsText);
@@ -68,10 +68,10 @@ describe('fastifyIntegration plugin', () => {
     );
 
     expect(actual.schemas).toEqual([
-      answerSchema.with$id,
       januarySchema.with$id,
       februarySchema.with$id,
       marchSchema.with$id,
+      answerSchema.with$id,
     ]);
   });