Quick links: Configuration parameters | Breaking changes |
---|
Release notes | Playground (beta)
typescript-generator is a tool for generating TypeScript definition files (.d.ts) from Java JSON classes. If you have REST service written in Java (or another JVM language) 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:
int
and Integer
, boolean
and Boolean
, etc.)String
Date
List
and Map
(including derived interfaces and implementation classes)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.
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.
In Gradle build you can use cz.habarta.typescript-generator
plugin like this:
plugins {
id 'cz.habarta.typescript-generator' version 'x.y.z'
}
generateTypeScript {
jsonLibrary = 'jackson2'
classes = [
'cz.habarta.typescript.generator.sample.Person'
]
outputKind = 'module'
}
For the Kotlin Gradle DSL you can alternatively use the cz.habarta.typescript-generator
plugin like this:
import cz.habarta.typescript.generator.JsonLibrary
import cz.habarta.typescript.generator.TypeScriptFileType
import cz.habarta.typescript.generator.TypeScriptOutputKind
plugins {
id("cz.habarta.typescript-generator") version "x.y.z"
}
tasks {
generateTypeScript {
jsonLibrary = JsonLibrary.jackson2
outputKind = TypeScriptOutputKind.module
outputFileType = TypeScriptFileType.implementationFile
...
}
}
You can run typescript-generator on demand using gradle generateTypeScript
command
or you can invoke it as part of another task by adding dependency from that task to generateTypeScript
task in Gradle build file.
More complete sample can be found here. Gradle plugin has the same features as Maven plugin, for detailed description see Maven generated site.
If you do not use Maven or Gradle you can invoke typescript-generator directly using TypeScriptGenerator.generateTypeScript()
method.
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 like com.example.ClassName$NestedClassName
classPatterns
- list of glob patterns like com.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
- value true
will include classes from automatically discovered REST resources, recommended if you have JAX-RS application without Application
subclassexcludeClasses
- list of fully qualified class names, excluded classes will be mapped to TypeScript any
type, if excluded class is a resource then this resource will not be scanned for used classesNote: 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 is configured using several parameters:
outputKind
(required parameter) - determines if and how module will be generated
global
, module
, ambientModule
outputFileType
- specifies TypeScript file type
declarationFile
(.d.ts) or implementationFile
(.ts)outputFile
- specifies path and name of output fileFor more details see Modules and Namespaces page.
Typescript-generator can generate not only TypeScript declarations for JSON Java classes but it can also generate client classes for REST services. Supported REST frameworks are JAX-RS and Spring. Client for JAX-RS service can be generated using generateJaxrsApplicationClient
parameter, client for Spring service can be generated using generateSpringApplicationClient
. Since Spring support is in separate module it is needed to add this module to typescript-generator dependencies. Here is example for Maven:
<plugin>
<groupId>cz.habarta.typescript-generator</groupId>
<artifactId>typescript-generator-maven-plugin</artifactId>
<version>${typescript-generator.version}</version>
<configuration>
<generateSpringApplicationClient>true</generateSpringApplicationClient>
...
</configuration>
<dependencies>
<dependency>
<groupId>cz.habarta.typescript-generator</groupId>
<artifactId>typescript-generator-spring</artifactId>
<version>${typescript-generator.version}</version>
</dependency>
</dependencies>
</plugin>
Releases are available from Maven Central Repository. Search for dependency information for your build tool or download typescript-generator-core directly.
For more detailed description of some topics see Wiki pages.
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 creates Model
.
It uses TypeProcessor
s for finding used classes.
For example if property type is List<Person>
it discovers that Person
class should be also parsed.
ModelParser
s are specific for each JSON library (for example Jackson2Parser
).ModelCompiler
transforms Java model to TypeScript model (Model
class to TsModel
class).
It uses TypeProcessor
s for mapping Java types to TypeScript types (for example for int
returns number
).Emitter
takes TsModel
and produces TypeScript declaration file.