diff --git a/.vscode/launch.json b/.vscode/launch.json index 49feb4528..bc654da57 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -15,7 +15,7 @@ "request": "launch", "runtimeExecutable": "node", "runtimeArgs": ["--nolazy", "-r", "ts-node/register"], - "args": ["ts-json-schema-generator.ts", "-p", "${file}"], + "args": ["bin/run.js", "${file}"], "cwd": "${workspaceFolder}", "internalConsoleOptions": "openOnSessionStart", "skipFiles": ["/**", "node_modules/**"] diff --git a/README.md b/README.md index f2913fe22..1f7b23801 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# ts-json-schema-generator +

ts-json-schema-generator

![Test](https://github.com/vega/ts-json-schema-generator/workflows/Test/badge.svg) [![codecov](https://codecov.io/gh/vega/ts-json-schema-generator/branch/master/graph/badge.svg)](https://codecov.io/gh/vega/ts-json-schema-generator) @@ -6,70 +6,212 @@ Extended version of [https://github.com/xiag-ag/typescript-to-json-schema](https://github.com/xiag-ag/typescript-to-json-schema). +--- + +- [Inspiration](#inspiration) +- [CLI Usage](#cli-usage) + - [Debugging](#debugging) + - [Options](#options) +- [`tjsg autocomplete [SHELL]`](#tjsg-autocomplete-shell) +- [`tjsg generate PATH`](#tjsg-generate-path) +- [`tjsg help [COMMAND]`](#tjsg-help-command) +- [Current state](#current-state) +- [Contributors](#contributors) +- [Programmatic Usage](#programmatic-usage) + - [Custom formatting](#custom-formatting) + - [Custom parsing](#custom-parsing) +- [Run locally](#run-locally) +- [Publish](#publish) + +
+ +## Inspiration + 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 -## 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). +
## CLI Usage -Run the schema generator with npx: +Run the schema generator by installing locally: -```bash -npx ts-json-schema-generator --path 'my/project/**/*.ts' --type 'My.Type.Name' -``` - -Or install the package and then run it - -```bash -npm install --save ts-json-schema-generator -./node_modules/.bin/ts-json-schema-generator --path 'my/project/**/*.ts' --type 'My.Type.Name' +```sh +$ npm i -D ts-json-schema-generator +$ npx tjsg generate 'my/project/**/*.ts' -t 'My.Type.Name' ``` 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. +### Debugging + +To help you troubleshoot issues, you can run the `tjsg-dev` command which will run the CLI in development mode. This will give you more verbose output: + +```sh +$ tjsg-dev 'my/project/**/*.ts' -t 'My.Type.Name' +``` + +
+ ### Options + + +- [`tjsg autocomplete [SHELL]`](#tjsg-autocomplete-shell) +- [`tjsg generate PATH`](#tjsg-generate-path) +- [`tjsg help [COMMAND]`](#tjsg-help-command) + +## `tjsg autocomplete [SHELL]` + +Display autocomplete installation instructions. + +``` +USAGE + $ tjsg autocomplete [SHELL] [-r] + +ARGUMENTS + SHELL (zsh|bash|powershell) Shell type + +FLAGS + -r, --refresh-cache Refresh cache (ignores displaying instructions) + +DESCRIPTION + Display autocomplete installation instructions. + +EXAMPLES + $ tjsg autocomplete + + $ tjsg autocomplete bash + + $ tjsg autocomplete zsh + + $ tjsg autocomplete powershell + + $ tjsg autocomplete --refresh-cache ``` - -p, --path Source file path - -t, --type Type name - -i, --id $id for generated schema - -f, --tsconfig Custom tsconfig.json path - -e, --expose Type exposing (choices: "all", "none", "export", default: "export") - -j, --jsDoc Read JsDoc annotations (choices: "none", "basic", "extended", default: "extended") - --markdown-description Generate `markdownDescription` in addition to `description`. - --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 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 + +_See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v3.0.18/src/commands/autocomplete/index.ts)_ + +## `tjsg generate PATH` + +Generate JSON schema from your Typescript sources + +``` +USAGE + $ tjsg generate PATH [-t ] [--top-ref] [-i ] [-p ] [-e all|none|export] [-j + none|basic|extended] [--markdown-description] [--sort-props] [--strict-tuples] [--type-check] [--ref-encode] + [--additional-properties] [--functions fail|comment|hide] [--minify | --color] [-o ] [--extra-tags ] + [--discriminator-type json-schema|open-api] + +ARGUMENTS + PATH Source root filepath + +FLAGS + -e, --expose=