Skip to content

raphaeljolivet/java2typescript

Repository files navigation

![Release](https://img.shields.io/github/release/raphaeljolivet/java2typescript.svg?label=latest release is)

Continuous Integration Build Status (for last commit on any branch)

Purpose

Java2Typescript provides a bridge between a Java REST service definition and a Typescript client.

It enables you to expose a full DTO model and REST services API as a clean typescript definition file, thus enabling strong type-checking on the models of your application.

This project is composed of 3 modules :

  • java2typescript-jackson: A Jackson module that generates typescript definition files for Java classes, using a Jackson ObjectMapper.
  • java2typescript-jaxrs: An extension to java2typescript-jackson that takes a JAX-RS annotated java class and produces both :
  • A Typescript definition file of the service (.d.ts), together with description of all needed DTO objects.
  • An .js implementation of the above definition as a REST client stub.
  • java2typescript-maven-plugin: A maven plugin to automate the generation of a .d.ts file and a .js implementation of REST services.
  • A sample web application that demonstrate the usage of java2typescript

Big picture

Here is a schema of the workflow for a typical project using j2ts : j2ts workflow

There are only two source files here :

  • Server side: AppRest.java with annotated JAX-RS services
  • Client side: App.ts

The detailed workflow is:

  1. AppRest.java contains the annotated JAX-RS service definition
  2. j2ts compiles the REST service definition into a .d.ts description file, and a .js file (runtime implementation)
  3. App.ts imports and uses the .d.ts file
  4. App.ts is compiled into a App.js file (by typescript compiler)

Usage

Please refer to the documentation of the maven plugin and the example below

Example

java2typescript handles all the HTTP REST standard itself, and provide REST services as vanilla Typescript methods, regardless of the HTTP method / mime to use.

Consider the following JAX-RS service

@Path( "/people" ) 
public interface PeopleRestService {
  
  
  @Produces( { MediaType.APPLICATION_JSON } )
  @GET
  public Collection< Person > getPeoples( @QueryParam( "page") @DefaultValue( "1" ) final int page ) {
    return peopleService.getPeople( page, 5 );
  }

  @Produces( { MediaType.APPLICATION_JSON } )
  @Path( "/{email}" )
  @GET
  public Person getPeople( @PathParam( "email" ) final String email ) {
    return peopleService.getByEmail( email );
  }
}

The maven plugin will produce the following typescript definition file :

export module People {

export interface PeopleRestService {
    getPeopleList(page: number): Person[];
    getPeople(email: string): Person;
}

export interface Person {
    email: string;
    firstName: string;
    lastName: string;
}

export var rootUrl: string;
export var peopleRestService: PeopleRestService;
export var adapter: (httpMethod: string, path: string, getParams: Object, postParams: Object, body: any)=> void;
}

The module People contains both the definitions of the DTO Person and the service PeopleRestService. It also provides 3 properties :

  • rootURL : URL of the service : Should be set before usage
  • peopleRESTService : An instance of the service
  • adapter : An adapter for REST service call. Set to Jquery adapter by default.

Then, in your application, you can call the service like so:

/// <reference path="People.d.ts" />
import p = People;
import Person = p.Person;
import prs = p.peopleRestService;

p.rootUrl = "http://someurl/root/";

var personList : Person[] = prs.getPeopleList(1);
var onePerson : Person = prs.getPeople("rrr@eee.com");

Don't forget to import the generated file People.js in the final HTML page.

Installation

To install the library using Maven, add the JitPack repository and java2typescript dependency:

...
<repositories>
  <repository>
      <id>jitpack.io</id>
      <url>https://jitpack.io</url>
  </repository>
</repositories>
...
<dependencies>
    <dependency>
        <groupId>com.github.raphaeljolivet.java2typescript</groupId>
        <artifactId>java2typescript-maven-plugin</artifactId>
        <version>v0.3.1</version><!-- see notes bellow to get either snapshot or specific commit or tag or other version -->
    </dependency>
</dependencies>
...

Note, artifacts for this project are built automatically by JitPack based on the github repository.

Note, if You are only interested in generating TypeScript definitions from Java classes, You can use java2typescript-jackson instead of java2typescript-maven-plugin as the artifact id.

Note, version can be replaced with

Licence

This project is licenced under the Apache v2.0 Licence

Credits

Jackson module is inspired from the jsonSchema module

About

A bridge between a Java model, REST services and Typescript definition

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages