Quick links: Configuration parameters | Breaking changes | Release notes
typescript-generator
typescript-generator is a tool for generating TypeScript definition files (.d.ts) from Java JSON classes. If you have REST service written in Java using object to JSON mapping you can use typescript-generator to generate TypeScript interfaces from Java classes.
For example for this Java class:
public class Person {
public String name;
public int age;
public boolean hasChildren;
public List<String> tags;
public Map<String, String> emails;
}
typescript-generator outputs this TypeScript interface:
interface Person {
name: string;
age: number;
hasChildren: boolean;
tags: string[];
emails: { [index: string]: string };
}
Supported types include:
- all Java primitive types with their corresponding wrappers (for example
int
andInteger
,boolean
andBoolean
, etc.) String
Date
- enum
- array
List
andMap
(including derived interfaces and implementation classes)- customized type mapping
For more details see Type Mapping Wiki page.
Note: typescript-generator works with compiled classes using Java reflection. It doesn't use source files (except for Javadoc feature). In Maven plugin this means either classes compiled from source files in the same module or classes added using
<dependency>
element.
Maven
In Maven build you can use typescript-generator-maven-plugin
like this:
<plugin>
<groupId>cz.habarta.typescript-generator</groupId>
<artifactId>typescript-generator-maven-plugin</artifactId>
<version>x.y.z</version>
<executions>
<execution>
<id>generate</id>
<goals>
<goal>generate</goal>
</goals>
<phase>process-classes</phase>
</execution>
</executions>
<configuration>
<jsonLibrary>jackson2</jsonLibrary>
<classes>
<class>cz.habarta.typescript.generator.Person</class>
</classes>
<outputKind>module</outputKind>
</configuration>
</plugin>
More complete sample can be found here. Detailed description how to configure typescript-generator-maven-plugin is on generated site.
Gradle
In Gradle build you can use cz.habarta.typescript-generator
plugin like this:
apply plugin: 'cz.habarta.typescript-generator'
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath group: 'cz.habarta.typescript-generator', name: 'typescript-generator-gradle-plugin', version: 'x.y.z'
}
}
generateTypeScript {
jsonLibrary = 'jackson2'
classes = [
'cz.habarta.typescript.generator.sample.Person'
]
outputFile = 'build/sample.d.ts'
outputKind = 'global'
namespace = 'Rest';
}
More complete sample can be found here. Gradle plugin has the same features as Maven plugin, for detailed description see Maven generated site.
Direct invocation
If you do not use Maven or Gradle you can invoke typescript-generator directly using TypeScriptGenerator.generateTypeScript()
method.
Input classes
Input classes can be specified using several parameters:
classes
- list of fully qualified class names, includes all listed classes and their dependencies,$
character is used for nested classes likecom.example.ClassName$NestedClassName
classPatterns
- list of glob patterns likecom.example.*Json
, includes all classes matched by the pattern, supported are*
and**
wildcardsclassesFromJaxrsApplication
- fully qualified name of JAX-RS application class, all classes used by application resources will be included, recommended if you have JAX-RS application classclassesFromAutomaticJaxrsApplication
- valuetrue
will include classes from automatically discovered REST resources, recommended if you have JAX-RS application withoutApplication
subclassexcludeClasses
- list of fully qualified class names, excluded classes will be mapped to TypeScriptany
type, if exluded class is a resource then this resource will not be scanned for used classes
Note: it is possible to use multiple parameters at the same time.
For more details see Class Names Glob Patterns and JAX RS Application Wiki pages.
Output parameters
Output is configured using several parameters:
outputKind
(required parameter) - determines if and how module will be generated- values are:
global
,module
,ambientModule
- values are:
outputFileType
- specifies TypeScript file type- values are:
declarationFile
(.d.ts) orimplementationFile
(.ts)
- values are:
outputFile
- specifies path and name of output file
For more details see Modules and Namespaces page.
Download
Releases are available from Maven Central Repository. Search for dependency information for your build tool or download typescript-generator-core directly.
Wiki
For more detailed description of some topics see Wiki pages.
Architecture
TypeScriptGenerator
has 3 main parts (ModelParser
, ModelCompiler
and Emitter
) which work together to produce TypeScript declarations for specified Java classes.
(Model) (TsModel)
ModelParser ==> ModelCompiler ==> Emitter
| |
V V
TypeProcessor
ModelParser
reads Java JSON classes and their properties using Java reflections and createsModel
. It usesTypeProcessor
s for finding used classes. For example if property type isList<Person>
it discovers thatPerson
class should be also parsed.ModelParser
s are specific for each JSON library (for exampleJackson2Parser
).ModelCompiler
transforms Java model to TypeScript model (Model
class toTsModel
class). It usesTypeProcessor
s for mapping Java types to TypeScript types (for example forint
returnsnumber
).Emitter
takesTsModel
and produces TypeScript declaration file.
Links
- http://www.rainerhahnekamp.com/type-safe-endpoints-with-typescript-and-java - blog post about using typescript-generator not only with Spring MVC
- http://www.jsweet.org/10-reasons-to-use-jsweet - blog post about JSweet transpiler mentions typescript-generator
- https://github.com/raphaeljolivet/java2typescript - tool similar to typescript-generator
Contributing
- this project targets Java 7
- keep pull requests small and focused (10 tips for better Pull Requests)
- do not add dependencies unless previously discussed in issue
Code formatting
- use 4 spaces for indentation in Java files
- sort java imports alphabetically, you can use wildcards
- please do not reformat whole files in IDE