1 | # typescript-json-schema
|
2 |
|
3 | [![npm version](https://img.shields.io/npm/v/typescript-json-schema.svg)](https://www.npmjs.com/package/typescript-json-schema) [![Build Status](https://travis-ci.org/YousefED/typescript-json-schema.svg?branch=master)](https://travis-ci.org/YousefED/typescript-json-schema)
|
4 |
|
5 | Generate json-schemas from your Typescript sources.
|
6 |
|
7 | ## Features
|
8 |
|
9 | * Compiles your Typescript program to get complete type information.
|
10 | * Translates required properties, extends, annotation keywords, property initializers as defaults. You can find examples for these features in the [test examples](https://github.com/YousefED/typescript-json-schema/tree/master/test/programs).
|
11 |
|
12 | ## Usage
|
13 |
|
14 | ### Command line
|
15 |
|
16 | * Install with `npm install typescript-json-schema -g`
|
17 | * Generate schema from a typescript type: `typescript-json-schema project/directory/tsconfig.json TYPE`
|
18 |
|
19 | To generate files for only _some_ types in `tsconfig.json` specify
|
20 | filenames or globs with the `--include` option. This is especially useful for large projects.
|
21 |
|
22 | In case no `tsconfig.json` is available for your project, you can directly specify the .ts files (this in this case we use some built-in compiler presets):
|
23 |
|
24 | * Generate schema from a typescript type: `typescript-json-schema "project/directory/**/*.ts" TYPE`
|
25 |
|
26 | The `TYPE` can either be a single, fully qualified type or `*` to generate the schema for all types.
|
27 |
|
28 | ```
|
29 | Usage: typescript-json-schema <path-to-typescript-files-or-tsconfig> <type>
|
30 |
|
31 | Options:
|
32 | --refs Create shared ref definitions. [boolean] [default: true]
|
33 | --aliasRefs Create shared ref definitions for the type aliases. [boolean] [default: false]
|
34 | --topRef Create a top-level ref definition. [boolean] [default: false]
|
35 | --titles Creates titles in the output schema. [boolean] [default: false]
|
36 | --defaultProps Create default properties definitions. [boolean] [default: false]
|
37 | --noExtraProps Disable additional properties in objects by default. [boolean] [default: false]
|
38 | --propOrder Create property order definitions. [boolean] [default: false]
|
39 | --required Create required array for non-optional properties. [boolean] [default: false]
|
40 | --strictNullChecks Make values non-nullable by default. [boolean] [default: false]
|
41 | --useTypeOfKeyword Use `typeOf` keyword (https://goo.gl/DC6sni) for functions. [boolean] [default: false]
|
42 | --out, -o The output file, defaults to using stdout
|
43 | --validationKeywords Provide additional validation keywords to include [array] [default: []]
|
44 | --include Further limit tsconfig to include only matching files [array] [default: []]
|
45 | --ignoreErrors Generate even if the program has errors. [boolean] [default: false]
|
46 | --excludePrivate Exclude private members from the schema [boolean] [default: false]
|
47 | --uniqueNames Use unique names for type symbols. [boolean] [default: false]
|
48 | --rejectDateType Rejects Date fields in type definitions. [boolean] [default: false]
|
49 | --id Set schema id. [string] [default: ""]
|
50 | ```
|
51 |
|
52 | ### Programmatic use
|
53 |
|
54 | ```ts
|
55 | import {resolve} from "path";
|
56 |
|
57 | import * as TJS from "typescript-json-schema";
|
58 |
|
59 | // optionally pass argument to schema generator
|
60 | const settings: TJS.PartialArgs = {
|
61 | required: true
|
62 | };
|
63 |
|
64 | // optionally pass ts compiler options
|
65 | const compilerOptions: TJS.CompilerOptions = {
|
66 | strictNullChecks: true
|
67 | }
|
68 |
|
69 | // optionally pass a base path
|
70 | const basePath = "./my-dir";
|
71 |
|
72 | const program = TJS.getProgramFromFiles([resolve("my-file.ts")], compilerOptions, basePath);
|
73 |
|
74 | // We can either get the schema for one file and one type...
|
75 | const schema = TJS.generateSchema(program, "MyType", settings);
|
76 |
|
77 |
|
78 | // ... or a generator that lets us incrementally get more schemas
|
79 |
|
80 | const generator = TJS.buildGenerator(program, settings);
|
81 |
|
82 | // all symbols
|
83 | const symbols = generator.getUserSymbols();
|
84 |
|
85 | // Get symbols for different types from generator.
|
86 | generator.getSchemaForSymbol("MyType");
|
87 | generator.getSchemaForSymbol("AnotherType");
|
88 | ```
|
89 |
|
90 | ```ts
|
91 | // In larger projects type names may not be unique,
|
92 | // while unique names may be enabled.
|
93 | const settings: TJS.PartialArgs = {
|
94 | uniqueNames: true
|
95 | };
|
96 |
|
97 | const generator = TJS.buildGenerator(program, settings);
|
98 |
|
99 | // A list of all types of a given name can then be retrieved.
|
100 | const symbolList = generator.getSymbols("MyType");
|
101 |
|
102 | // Choose the appropriate type, and continue with the symbol's unique name.
|
103 | generator.getSchemaForSymbol(symbolList[1].name);
|
104 |
|
105 | // Also it is possible to get a list of all symbols.
|
106 | const fullSymbolList = generator.getSymbols();
|
107 | ```
|
108 |
|
109 | `getSymbols('<SymbolName>')` and `getSymbols()` return an array of `SymbolRef`, which is of the following format:
|
110 |
|
111 | ```ts
|
112 | type SymbolRef = {
|
113 | name: string;
|
114 | typeName: string;
|
115 | fullyQualifiedName: string;
|
116 | symbol: ts.Symbol;
|
117 | };
|
118 | ```
|
119 |
|
120 | `getUserSymbols` and `getMainFileSymbols` return an array of `string`.
|
121 |
|
122 | ### Annotations
|
123 |
|
124 | The schema generator converts annotations to JSON schema properties.
|
125 |
|
126 | For example
|
127 |
|
128 | ```ts
|
129 | export interface Shape {
|
130 | /**
|
131 | * The size of the shape.
|
132 | *
|
133 | * @minimum 0
|
134 | * @TJS-type integer
|
135 | */
|
136 | size: number;
|
137 | }
|
138 | ```
|
139 |
|
140 | will be translated to
|
141 |
|
142 | ```json
|
143 | {
|
144 | "$ref": "#/definitions/Shape",
|
145 | "$schema": "http://json-schema.org/draft-07/schema#",
|
146 | "definitions": {
|
147 | "Shape": {
|
148 | "properties": {
|
149 | "size": {
|
150 | "description": "The size of the shape.",
|
151 | "minimum": 0,
|
152 | "type": "integer"
|
153 | }
|
154 | },
|
155 | "type": "object"
|
156 | }
|
157 | }
|
158 | }
|
159 | ```
|
160 |
|
161 | Note that we needed to use `@TJS-type` instead of just `@type` because of an [issue with the typescript compiler](https://github.com/Microsoft/TypeScript/issues/13498).
|
162 |
|
163 | ## Background
|
164 |
|
165 | Inspired and builds upon [Typson](https://github.com/lbovet/typson/), but typescript-json-schema is compatible with more recent Typescript versions. Also, since it uses the Typescript compiler internally, more advanced scenarios are possible.
|
166 |
|
167 | ## Debugging
|
168 |
|
169 | `npm run debug -- test/programs/type-alias-single/main.ts --aliasRefs true MyString`
|
170 |
|
171 | And connect via the debugger protocol.
|
172 |
|