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

Author: FoxxMD

README.md

@@ -4,17 +4,27 @@
 [![codecov](https://codecov.io/gh/vega/ts-json-schema-generator/branch/master/graph/badge.svg)](https://codecov.io/gh/vega/ts-json-schema-generator)
 [![npm version](https://img.shields.io/npm/v/ts-json-schema-generator.svg)](https://www.npmjs.com/package/ts-json-schema-generator)
 
-Extended version of [https://github.com/xiag-ag/typescript-to-json-schema](https://github.com/xiag-ag/typescript-to-json-schema).
+Extended version of
+[https://github.com/xiag-ag/typescript-to-json-schema](https://github.com/xiag-ag/typescript-to-json-schema).
 
-Inspired by [`YousefED/typescript-json-schema`](https://github.com/YousefED/typescript-json-schema). Here's the differences list:
+Inspired by
+[`YousefED/typescript-json-schema`](https://github.com/YousefED/typescript-json-schema).
+Here's the differences list:
 
--   this implementation avoids the use of `typeChecker.getTypeAtLocation()` (so probably it keeps correct type aliases)
--   processing AST and formatting JSON schema have been split into two independent steps
--   not exported types, interfaces, enums are not exposed in the `definitions` section in the JSON schema
+- this implementation avoids the use of `typeChecker.getTypeAtLocation()` (so
+  probably it keeps correct type aliases)
+- processing AST and formatting JSON schema have been split into two independent
+  steps
+- not exported types, interfaces, enums are not exposed in the `definitions`
+  section in the JSON schema
 
 ## Contributors
 
-This project is made possible by a [community of contributors](https://github.com/vega/ts-json-schema-generator/graphs/contributors). We welcome contributions of any kind (issues, code, documentation, examples, tests,...). Please read our [code of conduct](https://vega.github.io/vega/about/code-of-conduct).
+This project is made possible by a
+[community of contributors](https://github.com/vega/ts-json-schema-generator/graphs/contributors).
+We welcome contributions of any kind (issues, code, documentation, examples,
+tests,...). Please read our
+[code of conduct](https://vega.github.io/vega/about/code-of-conduct).
 
 ## CLI Usage
 
@@ -31,35 +41,43 @@ npm install --save ts-json-schema-generator
 ./node_modules/.bin/ts-json-schema-generator --path 'my/project/**/*.ts' --type 'My.Type.Name'
 ```
 
-Note that different platforms (e.g. Windows) may use different path separators so you may have to adjust the command above.
+Note that different platforms (e.g. Windows) may use different path separators
+so you may have to adjust the command above.
 
-Also note that you need to quote paths with `*` as otherwise the shell will expand the paths and therefore only pass the first path to the generator.
+Also note that you need to quote paths with `*` as otherwise the shell will
+expand the paths and therefore only pass the first path to the generator.
 
-By default, the command-line generator will use the `tsconfig.json` file in the current working directory, or the first parent directory that contains a `tsconfig.json` file up to the root of the filesystem. If you want to use a different `tsconfig.json` file, you can use the `--tsconfig` option. In particular, if you need to use different compilation options for types, you may want to create a separate `tsconfig.json` file for the schema generation only.
+By default, the command-line generator will use the `tsconfig.json` file in the
+current working directory, or the first parent directory that contains a
+`tsconfig.json` file up to the root of the filesystem. If you want to use a
+different `tsconfig.json` file, you can use the `--tsconfig` option. In
+particular, if you need to use different compilation options for types, you may
+want to create a separate `tsconfig.json` file for the schema generation only.
 
 ### Options
 
 ```
-  -p, --path <path>              Source file path
-  -t, --type <name>              Type name
-  -i, --id <name>                $id for generated schema
-  -f, --tsconfig <path>          Custom tsconfig.json path
-  -e, --expose <expose>          Type exposing (choices: "all", "none", "export", default: "export")
-  -j, --jsDoc <extended>         Read JsDoc annotations (choices: "none", "basic", "extended", default: "extended")
-  --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")
-  --minify                       Minify generated schema (default: false)
-  --unstable                     Do not sort properties
-  --strict-tuples                Do not allow additional items on tuples
-  --no-top-ref                   Do not create a top-level $ref definition
-  --no-type-check                Skip type checks to improve performance
-  --no-ref-encode                Do not encode references
-  -o, --out <file>               Set the output file (default: stdout)
-  --validation-keywords [value]  Provide additional validation keywords to include (default: [])
-  --additional-properties        Allow additional properties for objects with no index signature (default: false)
-  -V, --version                  output the version number
-  -h, --help                     display help for command
+-p, --path <path>              Source file path
+-t, --type <name>              Type name
+-i, --id <name>                $id for generated schema
+-f, --tsconfig <path>          Custom tsconfig.json path
+-e, --expose <expose>          Type exposing (choices: "all", "none", "export", default: "export")
+-j, --jsDoc <extended>         Read JsDoc annotations (choices: "none", "basic", "extended", default: "extended")
+--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
+--no-top-ref                   Do not create a top-level $ref definition
+--no-type-check                Skip type checks to improve performance
+--no-ref-encode                Do not encode references
+-o, --out <file>               Set the output file (default: stdout)
+--validation-keywords [value]  Provide additional validation keywords to include (default: [])
+--additional-properties        Allow additional properties for objects with no index signature (default: false)
+-V, --version                  output the version number
+-h, --help                     display help for command
 ```
 
 ## Programmatic Usage
@@ -90,13 +108,20 @@ Run the schema generator via `node main.js`.
 
 ### Custom formatting
 
-Extending the built-in formatting is possible by creating a custom formatter and adding it to the main formatter:
+Extending the built-in formatting is possible by creating a custom formatter and
+adding it to the main formatter:
 
-1. First we create a formatter, in this case for formatting function types (note that there is a built in one):
+1. First we create a formatter, in this case for formatting function types (note
+   that there is a built in one):
 
 ```ts
 // my-function-formatter.ts
-import { BaseType, Definition, FunctionType, SubTypeFormatter } from "ts-json-schema-generator";
+import {
+    BaseType,
+    Definition,
+    FunctionType,
+    SubTypeFormatter,
+} from "ts-json-schema-generator";
 import ts from "typescript";
 
 export class MyFunctionTypeFormatter implements SubTypeFormatter {
@@ -133,10 +158,16 @@ export class MyFunctionTypeFormatter implements SubTypeFormatter {
 }
 ```
 
-2. Then we add the formatter as a child to the core formatter using the augmentation callback:
+2. Then we add the formatter as a child to the core formatter using the
+   augmentation callback:
 
 ```ts
-import { createProgram, createParser, SchemaGenerator, createFormatter } from "ts-json-schema-generator";
+import {
+    createFormatter,
+    createParser,
+    createProgram,
+    SchemaGenerator,
+} from "ts-json-schema-generator";
 import { MyFunctionTypeFormatter } from "./my-function-formatter.ts";
 import fs from "fs";
 
@@ -147,12 +178,17 @@ const config = {
 };
 
 // We configure the formatter an add our custom formatter to it.
-const formatter = createFormatter(config, (fmt, circularReferenceTypeFormatter) => {
-    // If your formatter DOES NOT support children, e.g. getChildren() { return [] }:
-    fmt.addTypeFormatter(new MyFunctionTypeFormatter());
-    // If your formatter DOES support children, you'll need this reference too:
-    fmt.addTypeFormatter(new MyFunctionTypeFormatter(circularReferenceTypeFormatter));
-});
+const formatter = createFormatter(
+    config,
+    (fmt, circularReferenceTypeFormatter) => {
+        // If your formatter DOES NOT support children, e.g. getChildren() { return [] }:
+        fmt.addTypeFormatter(new MyFunctionTypeFormatter());
+        // If your formatter DOES support children, you'll need this reference too:
+        fmt.addTypeFormatter(
+            new MyFunctionTypeFormatter(circularReferenceTypeFormatter),
+        );
+    },
+);
 
 const program = createProgram(config);
 const parser = createParser(program, config);
@@ -168,30 +204,47 @@ fs.writeFile(outputPath, schemaString, (err) => {
 
 ### Custom parsing
 
-Similar to custom formatting, extending the built-in parsing works practically the same way:
+Similar to custom formatting, extending the built-in parsing works practically
+the same way:
 
 1. First we create a parser, in this case for parsing construct types:
 
 ```ts
 // my-constructor-parser.ts
-import { Context, StringType, ReferenceType, BaseType, SubNodeParser } from "ts-json-schema-generator";
+import {
+    BaseType,
+    Context,
+    ReferenceType,
+    StringType,
+    SubNodeParser,
+} from "ts-json-schema-generator";
 // use typescript exported by TJS to avoid version conflict
 import ts from "ts-json-schema-generator";
 
 export class MyConstructorParser implements SubNodeParser {
     supportsNode(node: ts.Node): boolean {
         return node.kind === ts.SyntaxKind.ConstructorType;
     }
-    createType(node: ts.Node, context: Context, reference?: ReferenceType): BaseType | undefined {
+    createType(
+        node: ts.Node,
+        context: Context,
+        reference?: ReferenceType,
+    ): BaseType | undefined {
         return new StringType(); // Treat constructors as strings in this example
     }
 }
 ```
 
-2. Then we add the parser as a child to the core parser using the augmentation callback:
+2. Then we add the parser as a child to the core parser using the augmentation
+   callback:
 
 ```ts
-import { createProgram, createParser, SchemaGenerator, createFormatter } from "ts-json-schema-generator";
+import {
+    createFormatter,
+    createParser,
+    createProgram,
+    SchemaGenerator,
+} from "ts-json-schema-generator";
 import { MyConstructorParser } from "./my-constructor-parser.ts";
 import fs from "fs";
 
@@ -221,20 +274,20 @@ fs.writeFile(outputPath, schemaString, (err) => {
 
 ## Current state
 
--   `interface` types
--   `enum` types
--   `union`, `tuple`, `type[]` types
--   `Date`, `RegExp`, `URL` types
--   `string`, `boolean`, `number` types
--   `"value"`, `123`, `true`, `false`, `null`, `undefined` literals
--   type aliases
--   generics
--   `typeof`
--   `keyof`
--   conditional types
--   functions
--   `Promise<T>` unwraps to `T`
--   Overrides (like `@format`)
+- `interface` types
+- `enum` types
+- `union`, `tuple`, `type[]` types
+- `Date`, `RegExp`, `URL` types
+- `string`, `boolean`, `number` types
+- `"value"`, `123`, `true`, `false`, `null`, `undefined` literals
+- type aliases
+- generics
+- `typeof`
+- `keyof`
+- conditional types
+- functions
+- `Promise<T>` unwraps to `T`
+- Overrides (like `@format`)
 
 ## Run locally
 
@@ -250,9 +303,17 @@ And connect via the debugger protocol.
 
 ## Publish
 
-Publishing is handled by a 2-branch [pre-release process](https://intuit.github.io/auto/docs/generated/shipit#next-branch-default), configured in `publish-auto.yml`. All changes should be based off the default `next` branch, and are published automatically.
-
--   PRs made into the default branch are auto-deployed to the `next` pre-release tag on NPM. The result can be installed with `npm install ts-json-schema-generator@next`
-    -   When merging into `next`, please use the `squash and merge` strategy.
--   To release a new stable version, open a PR from `next` into `stable` using this [compare link](https://github.com/vega/ts-json-schema-generator/compare/stable...next).
-    -   When merging from `next` into `stable`, please use the `create a merge commit` strategy.
+Publishing is handled by a 2-branch
+[pre-release process](https://intuit.github.io/auto/docs/generated/shipit#next-branch-default),
+configured in `publish-auto.yml`. All changes should be based off the default
+`next` branch, and are published automatically.
+
+- PRs made into the default branch are auto-deployed to the `next` pre-release
+  tag on NPM. The result can be installed with
+  `npm install ts-json-schema-generator@next`
+  - When merging into `next`, please use the `squash and merge` strategy.
+- To release a new stable version, open a PR from `next` into `stable` using
+  this
+  [compare link](https://github.com/vega/ts-json-schema-generator/compare/stable...next).
+  - When merging from `next` into `stable`, please use the
+    `create a merge commit` strategy.

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

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);

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", {

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