TypeScript Endpoints Generator

The TypeScript generator produces TypeScript files based on the information from an OpenApi document which is generated from Java files in src/main/java folder by default.

Note

Vaadin uses OpenAPI Specification as a middle layer between Java endpoints and TypeScript endpoint clients. The current implementation is based on OpenAPI specification 3.0. For details, please refer to the appendix at the end of this page.

Examples

A simple generated TypeScript files will look like the following snippet:

/**
 * User endpoints.
 *
 * This module has been generated from UserEndpoints.java
 * @module UserEndpoints
 */
import client from './connect-client.default';

/**
 * Check if a user is admin or not.
 *
 * @param id User id to be checked
 * Return Return true if the given user is an admin, otherwise false.
 */
export async function isAdmin(
  id?: number
) {
  return await client.call('UserEndpoints', 'isAdmin', {id});
}

The import client from './connect-client.default' is a static part of any generated file. connect-client.default.ts is another generated file which includes default configurations for the ConnectClient and exports its instance as client.

Each method in the generated modules is corresponding to a Java method in @Endpoint annotated classes. For example, the following Java code is corresponding to the generated UserEndpoints.ts:

/**
 * User endpoints.
 */
@Endpoint
public class UserEndpoints {
    /**
     * Check if a user is admin or not.
     *
     * @param id
     *            User id to be checked
     * @return Return true if the given user is an admin, otherwise false.
     */
    public boolean isAdmin(long id) {
        return id == 0;
    }
}
Note
For more information about type mapping between Java and TypeScript, please refer to type conversion page.

Type Nullability

Types are either nullable (optional) or non-nullable (required). By default, types are mapped and generated using the Java rules:

  • Any primitive type, such as int, is non-nullable.

  • Any reference type, such as String or Integer, is nullable.

  • A collection accepts null unless the collection item type is primitive.

  • A map accepts null unless the collection item type is primitive.

To make a type non-nullable, you need to put a @Nonnull annotation on it. You may use any annotation that has a nonnull (case-insensitive) name, for example:

  • javax.annotation.Nonnull

  • edu.umd.cs.findbugs.annotations.NonNull

  • lombok.NonNull

  • android.support.annotation.NonNull

  • org.eclipse.jdt.annotation.NonNull

  • any other annotation (including custom) that has the nonnull (case-insensitive) name.

@Endpoint
class MyEndpoint {
    public void setName(@Nonnull String firstName, @Nonnull String lastName, String middleName) {
        // omitted code
    }
}
export async function setName(
  firstName: string,
  lastName: string,
  middleName?: string
) {
  return await client.call('UserEndpoints', 'setName', {firstName, lastName, middleName});
}

In this case, if user calls UserEndpoints.setName('first', 'last') in TypeScript, the middle name is omitted and set as null when receiving in Java UserEndpoints.setName method. If the JavaType for that parameter is Optional, it receives Optional.empty();

Properties

public class MyBean {
    private long id;
    @Nonnull
    private String value;
    private String description;
    private Map<String, String> map;
    @Nonnull
    private List<String> list;
}
export default interface MyBean {
  id: number;
  value: string;
  description?: string;
  map?: Record<string, string | undefined>;
  list: Array<string | undefined>;
}

Return Type

@Endpoint
class MyEndpoint {
    @Nonnull
    public String getPhoneNumber() {
        // omitted code
    }
}
export async function getPhoneNumber() {
  return await client.call('UserEndpoints', 'getPhoneNumber');
}

Enum

The Java enum type is mapped to an enum TypeScript type. It is an object type, so you can work with it as you work with regular TypeScript objects.

public enum Enumeration {
    FIRST,
    SECOND,
}
export enum Enumeration {
  FIRST = "FIRST",
  SECOND = "SECOND"
}
Note
Complex Java enums mapping

The enum type is mapped in a simple way. No constructor-related Java features available in the TypeScript enum.

public enum Enumeration {
    FIRST("ONE"),
    SECOND("TWO");

    private String value;

    public Enumeration(String value) {
        this.value = value;
    }

    public String getValue() {
        return value;
    }
}
export enum Enumeration {
  FIRST = "FIRST",
  SECOND = "SECOND"
}

Appendix: How The Generator Generate TypeScript From OpenAPI Specification

Modules

The generator will collect all the tags field of all operations in the OpenAPI document. Each tag will generate a corresponding TypeScript file. The tag name is used for TypeScript module name as well as the file name. TsDoc of the class will be fetched from description field of the tag object which has the same name as the class.

Methods

Each exported method in a module is corresponding to a POST operation of a path item in paths object.

Note

Currently, the generator only supports POST operation. If a path item contains other operations than POST, the generator will stop processing.

The path must start with / as described in Patterned Fields. It is parsed as /<endpoint name>/<method name> which are used as parameters to call to Java endpoints in the backend. Method name from the path is also reused as the method name in the generated TypeScript file.

Method’s Parameters

Parameters of the method are taken from the application/json content of request body object. To get the result as [UserEndpoint.ts], the request body content should be:

{
 "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "User id to be checked"
          }
        }
      }
    }
  }
}

Type and description of each property are used for TsDoc that describes the parameter in more details.

Note

All the other content types of request body object are not ignored by the Vaadin Generator. It means that without the application/json content type, the method is considered as a no parameter one.

Method’s Return Type

Return type and its description are taken from the 200 response object. As same as request body object, the generator is only interested at application/json content type. The schema type indicates the return type and the description describes the result. Here is an example of a responses objects:

{
  "200": {
    "description": "Return true if the given user is an admin, otherwise false.",
    "content": {
      "application/json": {
        "schema": {
          "type": "boolean"
        }
      }
    }
  }
}
Note

At this point, the generator only takes the advantage of 200 response objects. Other response objects are ignored.

Method’s TsDoc

The TsDoc of the generated method is stored as description value of the POST operation in path item. A valid POST operation combined with [request-body] and [response-object] would look like:

{
  "tags": ["UserEndpoint"], 1
  "description": "Check if a user is admin or not.",
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "User id to be checked"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Return true if the given user is an admin, otherwise false.",
      "content": {
        "application/json": {
          "schema": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
  1. As mentioned in operation object specification, in Vaadin Generator, tags are used to classify operations into TypeScript files. It means each tag will have a corresponding generated TypeScript file. The operations, which contain more than one tag, will appear in all generated files. Empty tags operations will be placed in Default.ts file.

Note

Although multiple tags do not break the generator, it might be confusing in the development time when there are two exact same methods in different TypeScript files. It is recommended to have only one tag per operation.

Here is an example OpenAPI document which could generate the above [UserEndpoint.ts].

{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "My example application",
    "version" : "1.0.0"
  },
  "servers" : [ {
    "url" : "https://myhost.com/myendpoint",
    "description" : "Vaadin backend server"
  } ],
  "tags" : [ {
    "name" : "UserEndpoint",
    "description" : "User endpoint class."
  } ],
  "paths" : {
    "/UserEndpoint/isAdmin" : {
      "post": {
        "tags": ["UserEndpoint"],
        "description": "Check if a user is admin or not.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [ "id" ],
                "properties": {
                  "id": {
                    "type": "number",
                    "description": "User id to be checked"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Return true if the given user is an admin, otherwise false.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "boolean"
                }
              }
            }
          }
        }
      }
    }
  }
}