Maven Central Appveyor Stars

Quick links: Configuration parameters Breaking changes

Release notes | Playground (beta)

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:

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()
        jcenter()
    }
    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';
}

For the Kotlin Gradle DSL you can alternatively use the cz.habarta.typescript-generator plugin like this:

build.gradle.kts

import cz.habarta.typescript.generator.JsonLibrary
import cz.habarta.typescript.generator.TypeScriptFileType

plugins {
    id("cz.habarta.typescript-generator") version "x.y.z"
}

tasks {
    generateTypeScript {
        jsonLibrary = JsonLibrary.jackson2
        outputFileType = TypeScriptFileType.implementationFile
        ...
    }
}

settings.gradle.kts

We use this to resolve the plugin, as the plugin is not yet in the Gradle Plugin Repository

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
        jcenter()
    }
    resolutionStrategy {
        eachPlugin {
            if (requested.id.id == "cz.habarta.typescript-generator") {
                useModule("cz.habarta.typescript-generator:typescript-generator-gradle-plugin:${requested.version ?: "+"}")
            }
        }
    }
}

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.

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:

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:

For more details see Modules and Namespaces page.

REST frameworks

Typescript-generator can generate not only TypeScript declarations for JSON Java classes but it can also generate client classes for REST services. Suppported REST frameworks are JAXR-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>

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

Links

Contributing

Code formatting