ts json schema generator Télécharger - ts json schema generator Téléchargement du code source

générateur de schéma ts-json

Version étendue de https://github.com/xiag-ag/typescript-to-json-schema.

Inspiré de YousefED/typescript-json-schema . Voici la liste des différences :

cette implémentation évite l'utilisation de typeChecker.getTypeAtLocation() (donc elle conserve probablement les alias de type corrects)
le traitement AST et le formatage du schéma JSON ont été divisés en deux étapes indépendantes
les types, interfaces et énumérations non exportés ne sont pas exposés dans la section definitions du schéma JSON

Contributeurs

Ce projet est rendu possible grâce à une communauté de contributeurs. Nous acceptons les contributions de toute nature (problèmes, code, documentation, exemples, tests,...). Veuillez lire notre code de conduite.

Utilisation de la CLI

Exécutez le générateur de schéma avec npx :

npx ts-json-schema-generator --path ' my/project/**/*.ts ' --type ' My.Type.Name '

Ou installez le package puis exécutez-le

npm install --save ts-json-schema-generator
./node_modules/.bin/ts-json-schema-generator --path ' my/project/**/*.ts ' --type ' My.Type.Name '

Notez que différentes plates-formes (par exemple Windows) peuvent utiliser différents séparateurs de chemin, vous devrez donc peut-être ajuster la commande ci-dessus.

Notez également que vous devez citer les chemins avec * , sinon le shell développera les chemins et ne transmettra donc que le premier chemin au générateur.

Par défaut, le générateur de ligne de commande utilisera le fichier tsconfig.json dans le répertoire de travail actuel ou le premier répertoire parent contenant un fichier tsconfig.json jusqu'à la racine du système de fichiers. Si vous souhaitez utiliser un autre fichier tsconfig.json , vous pouvez utiliser l'option --tsconfig . En particulier, si vous devez utiliser différentes options de compilation pour les types, vous souhaiterez peut-être créer un fichier tsconfig.json distinct pour la génération du schéma uniquement.

Possibilités

  -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

Utilisation programmatique

 // main.js

const tsj = require ( "ts-json-schema-generator" ) ;
const fs = require ( "fs" ) ;

/** @type {import('ts-json-schema-generator/dist/src/Config').Config} */
const config = {
    path : "path/to/source/file" ,
    tsconfig : "path/to/tsconfig.json" ,
    type : "*" , // Or <type-name> if you want to generate schema for that one type only
} ;

const outputPath = "path/to/output/file" ;

const schema = tsj . createGenerator ( config ) . createSchema ( config . type ) ;
const schemaString = JSON . stringify ( schema , null , 2 ) ;
fs . writeFile ( outputPath , schemaString , ( err ) => {
    if ( err ) throw err ;
} ) ;

Exécutez le générateur de schéma via node main.js .

Formatage personnalisé

Il est possible d'étendre le formatage intégré en créant un formateur personnalisé et en l'ajoutant au formateur principal :

Nous créons d’abord un formateur, dans ce cas pour formater les types de fonctions (notez qu’il en existe un intégré) :

 // my-function-formatter.ts
import { BaseType , Definition , FunctionType , SubTypeFormatter } from "ts-json-schema-generator" ;
import ts from "typescript" ;

export class MyFunctionTypeFormatter implements SubTypeFormatter {
    // You can skip this line if you don't need childTypeFormatter
    public constructor ( private childTypeFormatter : TypeFormatter ) { }

    public supportsType ( type : BaseType ) : boolean {
        return type instanceof FunctionType ;
    }

    public getDefinition ( type : FunctionType ) : Definition {
        // Return a custom schema for the function property.
        return {
            type : "object" ,
            properties : {
                isFunction : {
                    type : "boolean" ,
                    const : true ,
                } ,
            } ,
        } ;
    }

    // If this type does NOT HAVE children, generally all you need is:
    public getChildren ( type : FunctionType ) : BaseType [ ] {
        return [ ] ;
    }

    // However, if children ARE supported, you'll need something similar to
    // this (see src/TypeFormatter/{Array,Definition,etc}.ts for some examples):
    public getChildren ( type : FunctionType ) : BaseType [ ] {
        return this . childTypeFormatter . getChildren ( type . getType ( ) ) ;
    }
}

Ensuite, nous ajoutons le formateur en tant qu'enfant au formateur principal à l'aide du rappel d'augmentation :

 import { createProgram , createParser , SchemaGenerator , createFormatter } from "ts-json-schema-generator" ;
import { MyFunctionTypeFormatter } from "./my-function-formatter.ts" ;
import fs from "fs" ;

const config = {
    path : "path/to/source/file" ,
    tsconfig : "path/to/tsconfig.json" ,
    type : "*" , // Or <type-name> if you want to generate schema for that one type only
} ;

// 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 program = createProgram ( config ) ;
const parser = createParser ( program , config ) ;
const generator = new SchemaGenerator ( program , parser , formatter , config ) ;
const schema = generator . createSchema ( config . type ) ;
const outputPath = "path/to/output/file" ;

const schemaString = JSON . stringify ( schema , null , 2 ) ;
fs . writeFile ( outputPath , schemaString , ( err ) => {
    if ( err ) throw err ;
} ) ;

Analyse personnalisée

Semblable au formatage personnalisé, l’extension de l’analyse intégrée fonctionne pratiquement de la même manière :

Nous créons d’abord un analyseur, dans ce cas pour analyser les types de construction :

 // my-constructor-parser.ts
import { Context , StringType , ReferenceType , BaseType , 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 {
        return new StringType ( ) ; // Treat constructors as strings in this example
    }
}

Ensuite, nous ajoutons l'analyseur en tant qu'enfant à l'analyseur principal en utilisant le rappel d'augmentation :

 import { createProgram , createParser , SchemaGenerator , createFormatter } from "ts-json-schema-generator" ;
import { MyConstructorParser } from "./my-constructor-parser.ts" ;
import fs from "fs" ;

const config = {
    path : "path/to/source/file" ,
    tsconfig : "path/to/tsconfig.json" ,
    type : "*" , // Or <type-name> if you want to generate schema for that one type only
} ;

const program = createProgram ( config ) ;

// We configure the parser an add our custom parser to it.
const parser = createParser ( program , config , ( prs ) => {
    prs . addNodeParser ( new MyConstructorParser ( ) ) ;
} ) ;

const formatter = createFormatter ( config ) ;
const generator = new SchemaGenerator ( program , parser , formatter , config ) ;
const schema = generator . createSchema ( config . type ) ;
const outputPath = "path/to/output/file" ;

const schemaString = JSON . stringify ( schema , null , 2 ) ;
fs . writeFile ( outputPath , schemaString , ( err ) => {
    if ( err ) throw err ;
} ) ;

État actuel

types interface
types enum
union , tuple , type[] types
Date , RegExp , types URL
type string , boolean , number
"value" , 123 , true , false , null , littéraux undefined
tapez des alias
génériques
typeof
keyof
types conditionnels
fonctions
Promise<T> se déroule en T
Remplacements (comme @format )

Exécuter localement

yarn --silent run run --path 'test/valid-data/type-mapped-array/*.ts' --type 'MyObject'

Déboguer

yarn --silent run debug --path 'test/valid-data/type-mapped-array/*.ts' --type 'MyObject'

Et connectez-vous via le protocole du débogueur.

AST Explorer est incroyable pour les développeurs de cet outil !

Publier

La publication est gérée par un processus de pré-version à 2 branches, configuré dans publish-auto.yml . Toutes les modifications doivent être basées sur la branche next par défaut et sont publiées automatiquement.

Les PR créés dans la branche par défaut sont automatiquement déployés vers la next balise de pré-version sur NPM. Le résultat peut être installé avec npm install ts-json-schema-generator@next
- Lors de la fusion avec next , veuillez utiliser la stratégie squash and merge .
Pour publier une nouvelle version stable, ouvrez un PR de next vers stable en utilisant ce lien de comparaison.
- Lors de la fusion de next vers stable , veuillez utiliser la stratégie create a merge commit .