Skip to main content

Setup & Usage

The package @odata2ts/odata2ts realizes the generation process and as such is the heart of the odata2ts system. It uses the metadata description of an OData service (V2 and V4) as its source to generate different sorts of artefacts that you can use in your TypeScript code.

Setup​

The base setup for the generator is part of the getting started guide: Generator Setup. So if you're already set up, go to usage

Install the generator as dev dependency with the weapon of your choice:

npm install --save-dev @odata2ts/odata2ts

Build Integration​

You have at least two approaches here: a) just commit the generated files or b) generate when building.

The main aspects here is whether your OData service will change often, because it's also in development, and how "clean" you want to have your build setup.

The easiest approach is just to commit the generated files.

Usually you would not commit generated stuff, but generate it as part of your build. Typically, you use the "scripts" block of the package.json along these lines:

{
  "scripts": {
    "gen-odata": "odata2ts",
    "build": "odata2ts && ORIGINAL_BUILD_COMMAND"
  }
}

Configuration​

For each OData service two settings must be specified:

  • source: the downloaded metadata file
  • output: the output directory for the generated files; warning: this folder gets wiped on generation

You can also let odata2ts download the metadata file for you:

  • sourceUrl: full URL to the root of your OData service, e.g. https://services.odata.org/TripPinRESTierService
    • use prettier option to pretty print the file
  • source: becomes the storage path to the downloaded file
  • see downloading metadata for more information

odata2ts doesn't necessarily requires a config file, since the essential settings are available as CLI options. However, the pure CLI usage is restricted to generating only one service. With the help of the config file, you centralize all your settings, allow for handling the generation for multiple services and have type-safety and a documentation at your fingertips. In other words, it's highly recommended to use the config file.

caution

On each generation run the output folder of each specified service gets completely cleaned! So create an own folder for each service and never use paths like src.

Config File​

Create a file at the root of your project (where package.json resides) and call it: odata2ts.config.ts. Create a variable of type ConfigFileOptions and default export it.

You get types and enums from the generator package @odata2ts/odata2ts.

The following example demonstrates the (almost) minimal configuration needed to generate typings for two OData services:

import { ConfigFileOptions, Modes } from "@odata2ts/odata2ts";

const config: ConfigFileOptions = {
  mode: Modes.models,
  services: {
    northwind: {
      source: "resource/northwind.xml",
      output: "build/northwind",
    },
    trippin: {
      sourceUrl: "https://services.odata.org/TripPinRESTierService",
      source: "resource/trippin.xml",
      output: "build/trippin",
      prettier: true
    }
  }
}
export default config;

Usage​

With the configuration file in place, we can simply call odata2ts without any options. For example, with yarn:

yarn odata2ts

Since the config file is able to handle multiple services, you may use arguments to address one or more of these services (without arguments all configured services get generated):

yarn odata2ts northwind
yarn odata2ts northwind trippin

Pure CLI usage​

Without the config file you need to set the two required settings via options:

SettingOptionShorthand
source--source-s
output--output-o
sourceUrl--sourceUrl-u
yarn odata2ts -s resource/trippin.xml -o build/trippin

Of course, you can always use any CLI option to override any other settings. See [./configuration#cli-options] for a listing of all available CLI options.