spring rest 2 ts is typescript generator which produces data model and services in typescript based on Spring MVC annotations. It supports generation for Angular and React
spring-rest2ts-generator generates TypeScript code based on Spring MVC REST controllers and data model for HTTP requests and responses.
spring-rest2ts-generator started from Spring MVC but we noticed that it is easy to support also JAX-RS annotations and such support
has been added in version 1.2.4. For model conversion Jackson or Gson annotations could be used.
In version 1.4.0 there is added support for jackson-js library which
allows to deserialize JSON to ES6 classes which gives possibility to use in the model types which are missing in the JSON like
Date, Map, Set and in the code we can use intanceof operator on instances. Details are in the paragraph
Jackon-js conversion listener
From model classes there are generated TypeScript interfaces and from REST controllers full working Angular services based on Observable API
or plain JavaScript services based on Promises API. The main idea is that Spring annotations describing REST endpoints have enough information
to compose HTTP request and call REST endpoints so TypeScript code could be automatically generated. Code created by typescript generator reduces the amount
of handwritten code on the frontend and gives type-safe API to the backend, changes in URL path are hidden, in case of REST endpoint refactoring,
generated code will reflect these changes which will avoid compile-time error in the web app which reduces time on testing
To add a dependency on spring-rest2ts-generator using Maven, use the following:
<dependency>
<groupId>com.blue-veery</groupId>
<artifactId>spring-rest2ts-generator</artifactId>
<version>1.5.1</version>
</dependency>
<dependency>
<groupId>com.blue-veery</groupId>
<artifactId>spring-rest2ts-spring</artifactId>
<version>1.5.1</version>
</dependency>
<dependency>
<groupId>com.blue-veery</groupId>
<artifactId>spring-rest2ts-spring-data</artifactId>
<version>1.5.1</version>
<!-- only if spring data is used-->
</dependency>
<dependency>
<groupId>com.blue-veery</groupId>
<artifactId>spring-rest2ts-jackson</artifactId>
<version>1.5.1</version>
</dependency>
<dependency>
<groupId>com.blue-veery</groupId>
<artifactId>spring-rest2ts-jax-rs</artifactId>
<version>1.5.1</version>
<!-- only if JAX-RS is used-->
</dependency>
<dependency>
<groupId>com.blue-veery</groupId>
<artifactId>spring-rest2ts-angular2json-impl</artifactId>
<version>1.5.1</version>
<!-- only if angular2json is used-->
</dependency>
<dependency>
<groupId>com.blue-veery</groupId>
<artifactId>spring-rest2ts-gson</artifactId>
<version>1.5.1</version>
<!-- only if Gson is used-->
</dependency>
<dependency>
<groupId>com.blue-veery</groupId>
<artifactId>spring-rest2ts-jackson-js</artifactId>
<version>1.5.1</version>
<!-- only if jackson-js is used-->
</dependency>
<dependency>
<groupId>com.blue-veery</groupId>
<artifactId>spring-rest2ts-webflux</artifactId>
<version>1.5.1</version>
<!-- only if webflux is used-->
</dependency>
Due to greater flexibility typescript generator is configured by code, no configuration files are needed.
This gives possibility to easily extend generator in places where it is needed
Here is the simplest generator configurator:
Rest2tsGenerator tsGenerator = new Rest2tsGenerator();
// Java Classes filtering
tsGenerator.setModelClassesCondition(new ExtendsJavaTypeFilter(BaseDTO.class));
tsGenerator.setRestClassesCondition(new ExtendsJavaTypeFilter(BaseCtrl.class));
// Java model classes converter setup
JacksonObjectMapper jacksonObjectMapper = new JacksonObjectMapper();
jacksonObjectMapper.setFieldsVisibility(JsonAutoDetect.Visibility.ANY);
modelClassesConverter = new ModelClassesToTsInterfacesConverter(jacksonObjectMapper);
tsGenerator.setModelClassesConverter(modelClassesConverter);
// Spring REST controllers converter
restClassesConverter = new SpringRestToTsConverter(new Angular4ImplementationGenerator());
tsGenerator.setRestClassesConverter(restClassesConverter);
// set of java root packages for class scanning
javaPackageSet = Collections.singleton("com.blueveery.springrest2ts.examples");
tsGenerator.generate(javaPackageSet, Paths.get("../target/ts-code"));
public class BaseDTO {
private int id;
@JsonFormat(shape = JsonFormat.Shape.NUMBER)
private Date updateTimeStamp;
}
public class OrderDTO extends BaseDTO {
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "dd-MM-yyyy hh:mm:ss")
private LocalDateTime orderTimestamp;
}
@Controller
@RequestMapping("api/order")
public class OrderCtrl {
@PostMapping(consumes = {"application/json"}, produces = {"application/json"})
@ResponseBody
@ResponseStatus(HttpStatus.CREATED)
public OrderDTO createOrder(@RequestBody OrderDTO entity) {
return entity;
}
@RequestMapping(path = "/{id}", method = RequestMethod.GET, produces = {"application/json"})
@ResponseBody
public OrderDTO getOrder(@PathVariable int id) {
return new OrderDTO();
}
}
export interface Base {
id: number;
updateTimeStamp: number;
}
export interface Order extends Base {
/**
* pattern : dd-MM-yyyy hh:mm:ss
*/
orderTimestamp: string;
}
@Injectable()
export class OrderService {
httpService: HttpClient;
public constructor(httpService: HttpClient) {
this.httpService = httpService;
}
public createOrder(entity: Order): Observable<Order> {
let headers = new HttpHeaders().set('Content-type', 'application/json');
return this.httpService.post<Order>('api/order', entity, {headers});
}
public getOrder(id: number): Observable<Order> {
return this.httpService.get<Order>('api/order/' + id + '');
}
}
export class OrderService {
baseURL: URL;
public constructor(baseURL: URL = new URL(window.document.URL)) {
this.baseURL = baseURL;
}
public createOrder(entity: Order): Promise<Order> {
const url = new URL('/api/order', this.baseURL);
return fetch(url.toString(), {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify(entity)
}).then(res => res.json());
}
public getOrder(id: number): Promise<Order> {
const url = new URL('/api/order/' + id + '', this.baseURL);
return fetch(url.toString(), {method: 'GET'}).then(res => res.json());
}
}
Module spring-rest2ts-examples contains few model classes and REST controllers, class TsCodeGenerationsTest and ExtendedTsCodeGenerationsTest contains few
ready to run configuration examples (they are not unit tests, just examples), each example generates code to directory
target/classes/test-webapp/src, its parent directory target/classes/test-webapp contains webpack and npm setup
which is valid for all generator configurations apart from configurableTsModulesConverter which has different entry points
due to changed module names. To compile generated TypeScript code just execute following commands in folder target/classes/test-webapp:
npm install
npm run build
or just review generated code in Your favourite IDE which supports TypeScript
Generator needs two filters to select java classes for which TypeScript types will be generated, these filters
allows to skip Java classes in given packages for which TypeScript generation is not needed. By default Rest2tsGenerator
for model classes and rest controllers has RejectJavaTypeFilter which rejects all classes in a given java packages.
Such filter could be used to skip generation for REST controllers when only Typescript types are needed for Java model classes.
There are following filters which allows to build complex conditions:
Java classes which describe payload model are generated to TypeScript interfaces. Java collections are converted into
JavaScript arrays, Java Map is converted into object where key has a string type and value is converted Typescript Type
During model serialization to JSON, object mapper is applying some mappings(some of them are required for example in
the JSON, Date type must be represented as string or number) based on some default configuration or dedicated annotations.
Currently, Jackson Object mapper and Gson Object mapper are supported.
JacksonObjectMapper allows to set fields, getters and setters visibility. Based on this Typescript
interface fields are generated. Following Jackson annotations are supported :
Following Gson annotations are supported:
exluder.excludeFieldsWithoutExposeAnnotation() only fields with this annotation are added to Typescriptexluder..withVersion(...) only fields witch matches version are added to Typescript, there is also added comment to Typescript fieldexluder..withVersion(...) only fields witch matches version are added to Typescript, there is also added comment to Typescript fieldGson object mapper is configured by Gson excluder so it gives all possibilities to filter classes and fields given by gson excluder.
Mapper can be also configured with FieldNamingStrategy to change fields names.
In Gson there is a problem with @JsonAdapter which could changes completely how object looks after serialization. This
problem could be divided in two cases:
Gson doesn’t support natively polymorphic types, in such case in root class there is required an additional field which will be a type denominator, such field could be also added by Conversion Listener
To use Gson Object mapper you need to pass it to modelClassesConverter in the configuration
From REST classes there is generated working implementation in TypeScript which based on Spring annotations builds complete
HTTP request. Such implementation depends also used JavaScript framework, there is different approach to HTTP calls in Angular and React
so SpringRestToTsConverter requires instance of ImplementationGenerator. There are available two such implementation generators
Angular4ImplementationGenerator - generates valid Angular services with methods which corresponds to REST endpoints,FetchBasedImplementationGenerator - generates valid plain JavaScript classes with methods which corresponds to REST endpoints,There are supported following Spring annotations:
Parameters with type ‘Pageable’ from spring data, now are supported by adding extension to spring converter:
restClassesConverter.getConversionExtensionList().add(new SpringDataRestConversionExtension());
Data from pageable are sent to server and server response with Page object which contains Pageable, fields which can be set
on client side are not readonly, namely:
export interface Pageable {
pageNumber: number;
pageSize: number;
sort?: Sort;
readonly paged?: boolean;
readonly offset?: number;
readonly unpaged?: boolean;
}
before REST method call in Pageable object pageNumber and pageSize must be set and optionally sort.
Others fields are calculated on the server and sent back to client in Page object
If parameter with type Pageable is marked with annotation @PageableDefault, parameter in TypeScript is optional
To generate typescript code from reactive REST controllers, apart from other configuration required for controllers
you need to use WebFluxConfigurator in the following way:
WebFluxConfigurator.configure(tsGenerator);
With such configuration Mono type is unpacked and type parameter for Mono is used as return type:
Mono<Product> is converted to Product
Flux type is converted into array where item type is taken from Flux type parameter:
Flux<Product> is converted to Product[]
Since version 1.2.4 there is provided JaxRsRestToTsConverter which converts JAX-RS controllers into TypeScript services.
It supports following JAX-RS annotations:
JaxRsRestToTsConverter converter can be used with existing implementation generators Angular4ImplementationGenerator
and FetchBasedImplementationGenerator so code could be generated for Angular as well as for frameworks where Promises are used.
JaxRsRestToTsConverter usage example:
ClassNameMapper classNameMapper = new SubstringClassNameMapper("ResourceImpl", "Service");
JaxRsRestToTsConverter jaxRsRestToTsConverter = new JaxRsRestToTsConverter(new Angular4ImplementationGenerator(), classNameMapper);
tsGenerator.setRestClassesConverter(jaxRsRestToTsConverter);
Class JaxRsGenerationTest contains examples how to generate TypeScript code from JAX-RS REST endpoints
jackson-js library which
allows to deserialize JSON to ES6 classes which gives possibility to use in the model types, which are missing in the JSON like
Date, Map, Set. In the code we can also use intanceof operator on instances.
This conversion is based on the following classes:
ModelClassesToTsClassesConverter which converts Java classes to Typescript classesJacksonAnnotationsConversionToJacksonJs it is conversion listener which extends conversion made by ModelClassesToTsClassesConverter and adds jackson-js decorators based on the Java types and Jackson annotationsJacksonJsModelSerializerExtension adds in REST services calls to objectMapper to serialize/deserialize objectsClass com/blueveery/springrest2ts/examples/test/JacksonJSTest has example how to configure generator for code generation
compatible with jackon-js library.
Current conversion supports following decorators:
@JsonTypeInfo, @JsonSubTypes, @JsonTypeName to allows jackosn-js deserialize polymorphic collections and fields@JsonClassType and @JsonProperty() on fields with proper metadata which allows jackosn-js library to deserialize JSON to ES6 class instancesType name conversion is supported for following settings on The Java side:
JsonTypeInfo.Id.NAME in that case there is required implementation of typeIdResolver which gets on input current class and inheritance root class and produces class nameJsonTypeInfo.Id.CLASS for decorators @JsonSubTypes, @JsonTypeName there is used full Java class nameJsonTypeInfo.Id.MINIMAL_CLASS for decorators @JsonSubTypes, @JsonTypeName there is used minimal Java class nameFor Java JsonTypeInfo.include() following settings how to include in the JSON type info are supported:
PROPERTY & EXISTING_PROPERTY mapped to PROPERTYWRAPPER_OBJECT mapped to WRAPPER_OBJECTWRAPPER_ARRAY mapped to WRAPPER_ARRAYClasses in one inheritance hierarchy must be mapped to the same TS module because derived types are used on the top level
class in JacksonJs decorators, which will cause circular dependencies between modules but the same problem will be at the
backend with packages.
Having possibility to map JSON to real ES6 class instances, tsGenerator has new mapping customTypeMappingForClassHierarchy
which allows to map Java class and all derived classes to specified TypeScript class. It makes sens mainly for collections.
If we want to say that all fields which has type Set or type which implements this interface should be mapped to JS Set
we can add following mappings:
tsGenerator.getCustomTypeMappingForClassHierarchy().put(Map.class, TypeMapper.tsMap);
tsGenerator.getCustomTypeMappingForClassHierarchy().put(Collection.class, TypeMapper.tsArrayCollection);
tsGenerator.getCustomTypeMappingForClassHierarchy().put(Set.class, TypeMapper.tsSet);
tsGenerator.getCustomTypeMappingForClassHierarchy().put(Date.class, TypeMapper.tsDate);
Settings above will map all Java
MapArray classSetDateCollection and Set the nearest Java type is selected so in this caseHashSet will be mapped to JS Set not to ArrayJS Date is supported if it is serialized to number, the same is for Enums. To add support for other JacksonJS
decorators, users could create own conversion listener and add it together with JacksonAnnotationsConversionToJacksonJs
to model converter. In JacksonAnnotationsConversionToJacksonJs we tried to add only the most basic JacksonJs decorators.
angular2-jsonapi is an TypeScript
library which converts in web application incoming JSON into classes and classes into JSON.
Given advantage is that TypeScript interfaces doesn’t exists in runtime in opposite to classes but to use classes,
conversion is required which is done by angular2-jsonapi library, to enable this conversions some TypeScript
decorators are required on generated TypeScript model classes. There is provided java model classes converter
ModelClassesToTsAngular2JsonApiConverter which adds following TypeScript decorators
First TypeScript class in the inheritance root has set base class to TypeScript JsonApiModel
as it is required by angular2-jsonapi library
JsonApiModelConfig decorator has parameter type which is type name, this field is generated
from TypeScript class name (name.toLowerCase()+“s”) or is taken from Java annotation JsonApiModelConfig. To customize
type name, Java model class must be annotated with JsonApiModelConfig annotation which is provided by module
<dependency>
<groupId>com.blue-veery</groupId>
<artifactId>spring-rest2ts-angular2json-api</artifactId>
<version>1.5.1</version>
</dependency>
which needs to be included in Java project.
Simple configuration:
//set model class converter
JacksonObjectMapper jacksonObjectMapper = new JacksonObjectMapper();
jacksonObjectMapper.setFieldsVisibility(JsonAutoDetect.Visibility.ANY);
ModelClassesToTsAngular2JsonApiConverter modelClassesConverter = new ModelClassesToTsAngular2JsonApiConverter(jacksonObjectMapper);
tsGenerator.setModelClassesConverter(modelClassesConverter);
ModelClassesToTsAngular2JsonApiConverter has also ability to generate model variable
which is a mapping from type name to TypeScript class, this mapping is required by angular2-jsonapi configuration object.
To have such config generated, generator configuration needs to create such variable,
ModelClassesToTsAngular2JsonApiConverter modelClassesConverter = new ModelClassesToTsAngular2JsonApiConverter(jacksonObjectMapper);
//models variable is optional, if not set it will not be generated, module selection is up to user decision
JavaPackageToTsModuleConverter javaPackageToTsModuleConverter = tsGenerator.getJavaPackageToTsModuleConverter();
//there is selected TypeScript module where there will be generated class for ManufacturerDTO.class
TSModule tsModuleForModelsVariable = javaPackageToTsModuleConverter.getTsModule(ManufacturerDTO.class);
JavaPackageToTsModuleConverter javaPackageToTsModuleConverter = tsGenerator.getJavaPackageToTsModuleConverter();
TSModule tsModuleForModelsVariable = javaPackageToTsModuleConverter.getTsModule(ManufacturerDTO.class);
modelClassesConverter.createModelsVariable("models", tsModuleForModelsVariable);
tsGenerator.setModelClassesConverter(modelClassesConverter);
Configuration examples are in class Angular2JsonApiTest
This converter is an experimental version, generated code could
contain some inconsistencies since we weren’t able to find rules
how to apply angular2-jsonapi decorators to fields, only examples,
base on which incorrect conclusions could be made!
Promise<<Mapped java type>>Promise<void>Generator takes as input set of java packages which should be scanned for java classes and output path where TypesScript
modules will be generated. There are required only root packages in case if following packages are present:
com.blueveery.springrest2ts.examples.ctrls. Generator discovers also nested classes,Modules converter defines, in which TypeScript module, should be placed generated TypeScript type for given Java class
There are two types of modules converters:
By default generator is using TsModuleCreatorConverter, this converter takes a few last subpackages from java package and joins
them using hyphen. For java package com.blueveery.springrest2ts.examples.ctrls it will create TS module examples-ctrls
if this converter is configured to use last two subpackages. This converter will create module for any found java class.
TsModuleCreatorConverter moduleConverter = new TsModuleCreatorConverter(3); // use three last subpackges
tsGenerator.setJavaPackageToTsModuleConverter(moduleConverter);
Imports between generated types are using path from root so in tsconfig.json, in the web project, in which generated code
is used, baseUrl must be defined as it is in examples.
ConfigurableTsModulesConverter takes as an input maping from java packages to typeScript module which allows to specify
name of each generated module. This generator optionally as an input takes also TsModuleCreatorConverter to generate modules
for packages which are missing in the mapping
HashMap<String, TSModule> packagesMap = new HashMap<>();
packagesMap.put("com.blueveery.springrest2ts.examples.model", new TSModule("model", Paths.get("app/sdk/model"), false));
TSModule servicesModule = new TSModule("services", Paths.get("app/sdk/services"), false);
packagesMap.put("com.blueveery.springrest2ts.examples.ctrls.core", servicesModule);
packagesMap.put("com.blueveery.springrest2ts.examples.ctrls", servicesModule);
ConfigurableTsModulesConverter moduleConverter = new ConfigurableTsModulesConverter(packagesMap);
tsGenerator.setJavaPackageToTsModuleConverter(moduleConverter);
Java enums could be serialized as strings or ordinals. If they are serialized to strings in TypesScript union of enum values
could be used, if enums are serialized to ordinals TypesScript enums could be generated. To handle this there are provided two
enums converters
and configured in code:
tsGenerator.setEnumConverter(new JavaEnumToTsUnionConverter());
or
tsGenerator.setEnumConverter(new JavaEnumToTsEnumConverter());
Between Java and TypeScript there are different naming conventions for example model classes could end with postfix “DTO”
which could be unwanted in generated Typescript model, REST controllers could have “Ctrl” postfix where generated
Angular services should have postfix “Service”. To handle this situation type name mappers are provided. Currently there is
only one implementation SubstringClassNameMapper but any one could crete new one by implementing interface ‘ClassNameMapper’
Each class converter is using name mapper so they can be defined for enum, model and REST classes
modelClassesConverter.setClassNameMapper(new SubstringClassNameMapper("DTO", ""));
restClassesConverter.setClassNameMapper(new SubstringClassNameMapper("Ctrl", "Service"));
During serialization some types are converted by default, such conversion does not depends on any annotations to learn how
convert types. For example UUID could be converted to string, Date to number or string/array of numbers. To handle such
situation generator has map of custom mapping which allows to define such new mappings:
tsGenerator.getCustomTypeMapping().put(UUID.class, TypeMapper.tsString);
tsGenerator.getCustomTypeMapping().put(BigInteger.class, TypeMapper.tsNumber);
tsGenerator.getCustomTypeMapping().put(LocalDateTime.class, TypeMapper.tsNumber);
tsGenerator.getCustomTypeMapping().put(LocalDate.class, new TSArray(TypeMapper.tsNumber));
Class TypeMapper has static fields for all base TypeScript types, and for other cases types could be created using TS model
like for array of numbers new TSArray(TypeMapper.tsNumber)
Since ver 1.2.6 there is a possibility to use a custom JSON serializers/deserializers in generated code. By default, there is used
StandardJsonSerializerExtension which is generating code based on standard JavaScript JSON object (JSON.stringify & JSON.parse).
Json5ModelSerializerExtension extension allows to use JSON5 serializer. Following code snippet is showing how to configure generator:
ImplementationGenerator implementationGenerator = new Angular4ImplementationGenerator();
implementationGenerator.setSerializationExtension(new Json5ModelSerializerExtension());
restClassesConverter = new SpringRestToTsConverter(implementationGenerator);
tsGenerator.setRestClassesConverter(restClassesConverter);
tsGenerator.generate(javaPackageSet, OUTPUT_DIR_PATH);
To provide own JSON serializers/deserializers extension, user should implement ModelSerializerExtension interface
TypeScript has s great feature to warn about cases where value could be null. To use it TS compiler option must be set
strictNullChecks and proper fields in model set as nullable or proper parameters in methods which make REST calls.
Generators support this by marking TS fields based on information taken from corresponding java classes. Generator is using
NullableTypesStrategy with default implementation DefaultNullableTypesStrategy
which marks types as nullable if
java.util.Optionaljavax.annotation.NullableMarks mean that field type is union of original field type and null;
DefaultNullableTypesStrategy has settings which allows to configure which of above option use, by default all they are used
DefaultNullableTypesStrategy nullableTypesStrategy = new DefaultNullableTypesStrategy();
nullableTypesStrategy.setUsePrimitiveTypesWrappers(false);
tsGenerator.setNullableTypesStrategy(nullableTypesStrategy);
Each converter( enum, model classes, rest classes) allows for registering conversion listeners, such listeners
give possibility to extend conversion with new functionality. Now there is one, such listener provided SwaggerConversionListener
which adds comments to TypeScript types based on swagger 2.0 io.swagger.oas.annotations.Operation annotation
restClassesConverter.getConversionListener().getConversionListenerSet().add(new SwaggerConversionListener());
Generated TypeScript code is not formatted. Code formatting from project to project
could have totally different requirements and it is suggested to use dedicated formatting library
for this purpose like:
Java compiler by default optimizes methods parameters names, to have readable parameters names in Typescript at least for
REST controllers modules this optimization should be switched off
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<compilerArgs>
<compilerArg>-parameters</compilerArg>
</compilerArgs>
</configuration>
</plugin>
In most cases such situation is just a bug but there could be a situations in which this is required to handle TypeScript field
as an union of getter and setter type, in this order. Special case of this situation is when getter or setter is missing.
For missing setter field in TypeScript it is marked as readonly. For missing getter (for example we send password but do not read them from server)
TypeScript field is union of undefined | <setter type> because after read from server such fields will have value of undefined
Java allows for overloaded methods what is not supported by TypeScript/JavaScript. To solve this problems if overloaded methods are met
in REST controller, generated method names in TypeScript are changed by appending in first round HTTP methods to TypeScript method name
if they differ, if not URL path is appended splitted on / and joined with _
Angular for modules with typings, reports an error : Module not found: Error: Can't resolve <module path>
We think that it is reported bug: https://github.com/angular/angular-cli/issues/4874 tsc compilation for generated modules
works fine. To overcome this problem generator by default, generates only normal modules *.ts. To generate ambient modules
following option must be set:
Rest2tsGenerator.generateAmbientModules = true;
RequestPart