Generate an OData client for JavaScript

The OData client generator allows you to generate custom OData client libraries for OData services. You can then access these services from your code using the client libraries.

You can use the SAP Cloud SDK generator both as a command-line interface (CLI) and programmatically.

All you need to use is a service metadata specification in the EDMX format (file ending can be .edmx or .xml).

Check this guide for downloading a specification from SAP Business Accelerator Hub.

Installation

Run this command in your project's terminal to install the generator as a devDependency:

npm install -D @sap-cloud-sdk/generator

note

We recommend to install the generator as a local dependency, because global installations hide the used generator version and cause problems when transpiling to JavaScript. If you must use a globally installed generator, install the@types/node and @sap-cloud-sdk/odata-v2 or @sap-cloud-sdk/odata-v4 package in your project to make the transpilation work. See Transpilation for more details. If you need to transpile sources without any local node_modules, you must manually execute the tsc on your own with a custom path mapping.

Generate a Client Using the Command Line Interface

The SAP Cloud SDK generator is primarily intended to be used on the command line.

Run

npx generate-odata-client --inputDir path/to/your/service-specifications --outputDir path/to/store/generated/modules

Adapt the path/to/your/service-specifications to the directory containing your service specifications in EDMX format, for example service-specifications/. Also adapt path/to/store/generated/modules to your OData client directory for example odata-client.

This will generate OData clients for all your service specifications and create a serviceMapping.json in your input directory. This file is used for generation and contains a mapping from the original file name to the following information:

• directoryName: the name of the subdirectory the client code will be generated into.
• servicePath: the URL path to be prepended before every request. By default, this is read from the EDMX file, if available. Otherwise, the value will be set as VALUE_IS_UNDEFINED, and an error will be logged. In this case, you can specify servicePath in the serviceMapping.json manually and re-generate again.
• npmPackageName: the name of the npm package, if a package.json file is generated. This information is optional.

This information can be adjusted manually and ensure that every run of the generator produces the same names for the generation.

Example:

{
  "MyService": {
    "directoryName": "my-service",
    "servicePath": "/odata/v2",
    "npmPackageName": "my-service"
  }
}

By default, the generated module contains the following sources:

• TypeScript code (.ts) representing request builders, entity representations, and if needed representations for complex types as well as function/action imports.
• All of the above as transpiled sources, including JavaScript sources (.js), type definition files (.d.ts), and sourcemap files (.js.map and .d.ts.map).
• An .npmrc.
• A package.json.
• A typedoc.json.
• A tsconfig.json.

The generation always includes the TypeScript sources. All other files can be excluded from the generation - see the options below.

Options

Run generate-odata-client --help for additional options.

Option, Aliases	Default	Description
-i, --inputDir (required)	-	This directory will be recursively searched for .edmx/.xml files.
-o, --outputDir (required)	-	Directory to save the generated code in.
-s, --serviceMapping,	inputDir/service-mapping.json	Configuration file to ensure consistent names between multiple generation runs with updated / changed metadata files. Will be generated if not existent.
--forceOverwrite (deprecated in 2.12.0)	false	Exit when encountering a file that already exists. When set to true, it will be overwritten instead. Please note that compared to the --clearOutputDir option, this will not delete outdated files.
--overwrite (available since 2.12.0)	false	Exit when encountering a file that already exists. When set to true, it will be overwritten instead. Please note that compared to the --clearOutputDir option, this will not delete outdated files.
--clearOutputDir	false	Deletes EVERYTHING in the specified output directory before generating code.
--generateNpmrc (deprecated)	true	Generate a .npmrc file specifying a registry for @sap scoped dependencies.
--generateTypedocJson	true	Generates a typedoc.json file for each package, used for the corresponding "doc" npm script.
--generatePackageJson (deprecated in 2.12.0)	true	Generate a package.json file, specifying dependencies and scripts for compiling and generating documentation.
--packageJson (available since 2.12.0)	true	Generate a package.json file, specifying dependencies and scripts for compiling and generating documentation.
--versionInPackageJson (deprecated in 2.6.0)	Version of the generator	By default, when generating package.json file, the generator will set a version by using the generator version. It can also be set to a specific version.
--include available since 2.6.0	''	Glob describing additional files to be added to the each generated service directory - relative to inputDir.
--generateJs	true	Generates transpiled .js, .js.map, .d.ts and .d.ts.map files. When set to false, the generator will only generate .ts files.
--processesJsGeneration (deprecated in 2.12.0)	16	Number of processes used for transpilation of JavaScript files.
--transpilationProcesses (available since 2.12.0)	16	Number of processes used for transpilation of JavaScript files.
--generateCSN (deprecated in 2.12.0)	false	A CSN file will be generated for each service definition in the output directory.
--prettierConfig (available since 2.11.0)	default prettier config	Configuration file for the prettier if you want to change the default value

Generate a Client Programmatically

You can also use the generator programmatically. You will have to provide the options.

import { generate } from '@sap-cloud-sdk/generator';

// Create your options, adapt the input & output directory as well as the package name according to your setup.
const inputDir = 'service-specifications';
const outputDir = 'odata-client';

// Create your project datastructure with all sourcefiles based on your options
const generatorConfig = {
  overwrite: true,
  generateJs: false,
  useSwagger: false,
  readme: false,
  clearOutputDir: true,
  generateNpmrc: false,
  generateTypedocJson: false,
  packageJson: false,
  generateCSN: false,
  sdkAfterVersionScript: false,
  s4hanaCloud: false
  /* optional:
    serviceMapping: 'test/directory',
    changelogFile: 'test/directory',
    include: 'glob of files to include'
  */
};

// generate your project, you can also redefine options
generate({
  ...generatorConfig,
  inputDir,
  outputDir
});

npm Packages Versus Local Clients

The SAP Cloud SDK OData client generator generates TypeScript code. By default, the generator creates all sources needed for an npm package. It transpiles the generated sources to JavaScript and provides a package.json for the client. This differs from the OpenAPI generator and will likely change in a future major version upgrade.

If you want to publish a generated client to an npm registry, you can work with the default configuration. Please make sure to check intellectual property regulations before publishing to a public registry.

If you want to use the generated client in your code without sharing it, you can omit the generation of a package.json with the generatePackageJson flag. Additionally, if you work with TypeScript you can skip transpilation with the --generateJs flag. The generated clients depend on the @sap-cloud-sdk/odata-v2 or @sap-cloud-sdk/odata-v4 packages, depending on the OData version of the service. You have to make sure, there is a local reference to these packages, by running:

npm install @sap-cloud-sdk/odata-v2

or:

npm install @sap-cloud-sdk/odata-v4

respectively.

Transpilation

If you installed the generator globally and want to transpile the generated code, you have to install the required dependency (or devDependency) for your client (sap-cloud-sdk/odata-v2 or sap-cloud-sdk/odata-v4) prior to generation. You do this by running:

npm install -D @sap-cloud-sdk/odata-v2

or:

npm install -D @sap-cloud-sdk/odata-v4

respectively.

If you installed the generator as a devDependency, transpilation will work without additional steps.

Prettier

Since version 2.11.0, the SAP Cloud SDK runs prettier on the generated sources using a default prettier config. The prettier formats only TypeScript files (.ts and .d.ts) to avoid broken source maps. If you are not happy with the configuration you can provide a custom configuration using the prettierConfig command line argument. Note that this formatting is done in-memory before the generator emits the files, so no expensive additional I/O is required. Alternatively, you can execute a custom formatting step after the generation is finished.

Note that custom formatting steps could break source maps when you generate a JavaScript client (option generateJs enabled). We recommend excluding JavaScript clients from formatting because the generated .js and .map.js files are not meant for humans to read.