feat: Generate titles from definition names

All root child definitions have a 'title' added to their definition if the opt-in definitionTitles option is set
vega · Dec 10, 2024 · eaf3b87 · eaf3b87
1 parent d500564
commit eaf3b87
Show file tree

Hide file tree

Showing 7 changed files with 177 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -49,6 +49,7 @@ By default, the command-line generator will use the `tsconfig.json` file in the
   --markdown-description         Generate `markdownDescription` in addition to `description`.
   --functions <functions>        How to handle functions. `fail` will throw an error. `comment` will add a comment. `hide` will treat the function like a NeverType or HiddenType.
                                  (choices: "fail", "comment", "hide", default: "comment")
+  --definition-titles            Generates titles from definition names
   --minify                       Minify generated schema (default: false)
   --unstable                     Do not sort properties
   --strict-tuples                Do not allow additional items on tuples

diff --git a/src/Config.ts b/src/Config.ts
@@ -16,6 +16,7 @@ export interface Config {
     additionalProperties?: boolean;
     discriminatorType?: "json-schema" | "open-api";
     functions?: FunctionOptions;
+    definitionTitles?: boolean;
 }
 
 export type CompletedConfig = Config & typeof DEFAULT_CONFIG;
@@ -36,4 +37,5 @@ export const DEFAULT_CONFIG: Omit<Required<Config>, "path" | "type" | "schemaId"
     additionalProperties: false,
     discriminatorType: "json-schema",
     functions: "comment",
+    definitionTitles: false,
 };
diff --git a/src/SchemaGenerator.ts b/src/SchemaGenerator.ts
@@ -135,6 +135,9 @@ export class SchemaGenerator {
             const name = child.getName();
             if (!(name in definitions)) {
                 definitions[name] = this.typeFormatter.getDefinition(child.getType());
+                if (this.config?.definitionTitles) {
+                    definitions[name].title = name;
+                }
             }
             return definitions;
         }, childDefinitions);

diff --git a/test/config.test.ts b/test/config.test.ts
@@ -229,6 +229,17 @@ describe("config", () => {
         }),
     );
 
+    it(
+        "definition-titles",
+        assertSchema("definition-titles", {
+            type: "MyObject",
+            expose: "export",
+            topRef: false,
+            definitionTitles: true,
+            jsDoc: "none",
+        }),
+    );
+
     it(
         "jsdoc-complex-none",
         assertSchema("jsdoc-complex-none", {

diff --git a/test/config/definition-titles/main.ts b/test/config/definition-titles/main.ts
@@ -0,0 +1,36 @@
+export interface ExportInterface {
+    exportValue: string;
+}
+export type ExportAlias = ExportInterface;
+
+interface PrivateInterface {
+    privateValue: string;
+}
+type PrivateAlias = PrivateInterface;
+
+interface MixedInterface {
+    mixedValue: ExportAlias;
+}
+export type MixedAlias = PrivateInterface;
+
+export type PublicAnonymousTypeLiteral = {
+    publicValue: string;
+};
+
+type PrivateAnonymousTypeLiteral = {
+    privateValue: string;
+};
+
+export interface MyObject {
+    exportInterface: ExportInterface;
+    exportAlias: ExportAlias;
+
+    privateInterface: PrivateInterface;
+    privateAlias: PrivateAlias;
+
+    mixedInterface: MixedInterface;
+    mixedAlias: MixedAlias;
+
+    publicAnonymousTypeLiteral: PublicAnonymousTypeLiteral;
+    privateAnonymousTypeLiteral: PrivateAnonymousTypeLiteral;
+}
diff --git a/test/config/definition-titles/schema.json b/test/config/definition-titles/schema.json
@@ -0,0 +1,122 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "ExportAlias": {
+      "$ref": "#/definitions/ExportInterface",
+      "title": "ExportAlias"
+    },
+    "ExportInterface": {
+      "additionalProperties": false,
+      "properties": {
+        "exportValue": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "exportValue"
+      ],
+      "title": "ExportInterface",
+      "type": "object"
+    },
+    "MixedAlias": {
+      "additionalProperties": false,
+      "properties": {
+        "privateValue": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "privateValue"
+      ],
+      "title": "MixedAlias",
+      "type": "object"
+    },
+    "PublicAnonymousTypeLiteral": {
+      "additionalProperties": false,
+      "properties": {
+        "publicValue": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "publicValue"
+      ],
+      "title": "PublicAnonymousTypeLiteral",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "exportAlias": {
+      "$ref": "#/definitions/ExportAlias"
+    },
+    "exportInterface": {
+      "$ref": "#/definitions/ExportInterface"
+    },
+    "mixedAlias": {
+      "$ref": "#/definitions/MixedAlias"
+    },
+    "mixedInterface": {
+      "additionalProperties": false,
+      "properties": {
+        "mixedValue": {
+          "$ref": "#/definitions/ExportAlias"
+        }
+      },
+      "required": [
+        "mixedValue"
+      ],
+      "type": "object"
+    },
+    "privateAlias": {
+      "additionalProperties": false,
+      "properties": {
+        "privateValue": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "privateValue"
+      ],
+      "type": "object"
+    },
+    "privateAnonymousTypeLiteral": {
+      "additionalProperties": false,
+      "properties": {
+        "privateValue": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "privateValue"
+      ],
+      "type": "object"
+    },
+    "privateInterface": {
+      "additionalProperties": false,
+      "properties": {
+        "privateValue": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "privateValue"
+      ],
+      "type": "object"
+    },
+    "publicAnonymousTypeLiteral": {
+      "$ref": "#/definitions/PublicAnonymousTypeLiteral"
+    }
+  },
+  "required": [
+    "exportInterface",
+    "exportAlias",
+    "privateInterface",
+    "privateAlias",
+    "mixedInterface",
+    "mixedAlias",
+    "publicAnonymousTypeLiteral",
+    "privateAnonymousTypeLiteral"
+  ],
+  "type": "object"
+}
diff --git a/ts-json-schema-generator.ts b/ts-json-schema-generator.ts
@@ -36,6 +36,7 @@ const args = new Command()
             .choices(["fail", "comment", "hide"])
             .default("comment"),
     )
+    .option("--definition-titles", "Generate titles from defintion names", false)
     .option("--minify", "Minify generated schema", false)
     .option("--unstable", "Do not sort properties")
     .option("--strict-tuples", "Do not allow additional items on tuples")
@@ -56,6 +57,7 @@ const args = new Command()
 
 const config: Config = {
     minify: args.minify,
+    definitionTitles: args.definitionTitles,
     path: args.path,
     tsconfig:
         typeof args.tsconfig === "string" ? args.tsconfig : findConfigFile(process.cwd(), (f) => tsSys.fileExists(f)),