typescript-json-schema

npm version Build Status

Generate json-schemas from your Typescript sources.

Features

  • Compiles your Typescript program to get complete type information.
  • Translates required properties, extends, annotation keywords, property initializers as defaults. You can find examples for these features in the test examples.

Usage

Command line

  • Install with npm install typescript-json-schema -g
  • Generate schema from a typescript type: typescript-json-schema project/directory/tsconfig.json fully.qualified.type.to.generate

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

  • Generate schema from a typescript type: typescript-json-schema "project/directory/**/*.ts" fully.qualified.type.to.generate
Usage: node typescript-json-schema.js <path-to-typescript-files-or-tsconfig> <type>

Options:
  --refs                Create shared ref definitions.                               [boolean] [default: true]
  --aliasRefs           Create shared ref definitions for the type aliases.          [boolean] [default: false]
  --topRef              Create a top-level ref definition.                           [boolean] [default: false]
  --titles              Creates titles in the output schema.                         [boolean] [default: false]
  --defaultProps        Create default properties definitions.                       [boolean] [default: false]
  --noExtraProps        Disable additional properties in objects by default.         [boolean] [default: false]
  --propOrder           Create property order definitions.                           [boolean] [default: false]
  --required            Create required array for non-optional properties.           [boolean] [default: false]
  --strictNullChecks    Make values non-nullable by default.                         [boolean] [default: false]
  --useTypeOfKeyword    Use `typeOf` keyword (https://goo.gl/DC6sni) for functions.  [boolean] [default: false]
  --out, -o             The output file, defaults to using stdout
  --validationKeywords  Provide additional validation keywords to include            [array]   [default: []]

Programmatic use

import {resolve} from "path";

import {CompilerOptions} from "typescript";
import * as TJS from "typescript-json-schema";

// optionally pass argument to schema generator
const settings: TJS.PartialArgs = {
    generateRequired: true
};

// optionally pass ts compiler options
compilerOptions: CompilerOptions = {
    strictNullChecks: true
}

const program = TJS.getProgramFromFiles([resolve("my-file.ts")], compilerOptions);

// We can either get the schema for one file and one type...
const schema = TJS.generateSchema(program, "MyType", settings);


// ... or a generator that lets us incrementally get more schemas

const generator = TJS.buildGenerator(program, settings);

// all symbols
const symbols = generator.getUserSymbols();

// Get symbols for different types from generator.
generator.getSchemaForSymbol("MyType");
generator.getSchemaForSymbol("AnotherType");

Annotations

The schema generator converts annotations to JSON schema properties.

For example

export interface Shape {
    /**
     * The size of the shape.
     *
     * @minimum 0
     * @TJS-type integer
     */
    size: number;
}

will be translated to

{
    "$ref": "#/definitions/Shape",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "definitions": {
        "Shape": {
            "properties": {
                "size": {
                    "description": "The size of the shape.",
                    "minimum": 0,
                    "type": "integer"
                }
            },
            "type": "object"
        }
    }
}

Note that we needed to use @TJS-type instead of just @type because of an issue with the typescript compiler.

Background

Inspired and builds upon 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.



typescript-json-schema

NPM版本data-canonical-src 建立状态

从您的Typescript源生成json-schemas

功能

  • 编译您的Typescript程序以获取完整的类型信息。
  • 将所需属性,扩展名,注释关键字,属性初始值设定为默认值。您可以在测试示例中找到这些功能的示例。

用法

命令行

  • 使用 npm安装typescript-json-schema -g
  • 安装
  • 从typescript类型生成模式: typescript-json-schema project / directory / tsconfig.json fully.qualified.type.to.generate

如果您的项目没有tsconfig.json,您可以直接指定.ts文件(在这种情况下,我们使用一些内置的编译器预设):

  • 从typescript类型生成模式: typescript-json-schemaproject / directory / ** / *。tsfully.qualified.type.to.generate
Usage: node typescript-json-schema.js <path-to-typescript-files-or-tsconfig> <type>

Options: –refs Create shared ref definitions. [boolean] [default: true] –aliasRefs Create shared ref definitions for the type aliases. [boolean] [default: false] –topRef Create a top-level ref definition. [boolean] [default: false] –titles Creates titles in the output schema. [boolean] [default: false] –defaultProps Create default properties definitions. [boolean] [default: false] –noExtraProps Disable additional properties in objects by default. [boolean] [default: false] –propOrder Create property order definitions. [boolean] [default: false] –required Create required array for non-optional properties. [boolean] [default: false] –strictNullChecks Make values non-nullable by default. [boolean] [default: false] –useTypeOfKeyword Use typeOf keyword (https://goo.gl/DC6sni) for functions. [boolean] [default: false] –out, -o The output file, defaults to using stdout –validationKeywords Provide additional validation keywords to include [array] [default: []]

程序化使用

import {resolve} from "path";

import {CompilerOptions} from "typescript"; import * as TJS from "typescript-json-schema";

// optionally pass argument to schema generator const settings: TJS.PartialArgs = { generateRequired: true };

// optionally pass ts compiler options compilerOptions: CompilerOptions = { strictNullChecks: true }

const program = TJS.getProgramFromFiles([resolve("my-file.ts")], compilerOptions);

// We can either get the schema for one file and one type… const schema = TJS.generateSchema(program, "MyType", settings);

// … or a generator that lets us incrementally get more schemas

const generator = TJS.buildGenerator(program, settings);

// all symbols const symbols = generator.getUserSymbols();

// Get symbols for different types from generator. generator.getSchemaForSymbol("MyType"); generator.getSchemaForSymbol("AnotherType");

注释

模式生成器将注释转换为JSON模式属性。

例如

export interface Shape {
    /**
     * The size of the shape.
     *
     * @minimum 0
     * @TJS-type integer
     */
    size: number;
}

将被翻译成

{
    "$ref": "#/definitions/Shape",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "definitions": {
        "Shape": {
            "properties": {
                "size": {
                    "description": "The size of the shape.",
                    "minimum": 0,
                    "type": "integer"
                }
            },
            "type": "object"
        }
    }
}

请注意,由于 @ TJS-type 而不是 @type TypeScript / issues / 13498>与typescript编译器的问题

背景

启发并建立在 Typson 上,但typescript-json-schema与更新的Typescript版本兼容。此外,由于内部使用了Typescript编译器,所以可以使用更高级的场景。




相关问题推荐