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 development dependency`:

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

note

It is recommended 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 compiler 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 --input 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.

An options-per-service.json file is created using the --optionsPerService option.

• When set to a directory path, an options-per-service.json file is read from or created in the given directory.
• When set to a file path, the file is read or created with the given name.

This file is used for customizing subdirectory naming 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.
• packageName: the name of the npm package, if a package.json file is generated. This information is optional.
• basePath: the URL path to be prepended before every request (e.g. '/sap/opu/odata/sap/' for SAP S/4HANA services). The SDK will try to determine this value from either the EDMX or Swagger file. However, if automatic determination fails, client generation will also fail. In that case, to generate a client successfully, you can do either of the following:
  • Manually specify the basePath in the options-per-service.json file and re-generate the client, or
  • Set the --skipValidation option to true, in which case, the SDK will set the basePath value to / and log a warning message.

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

Example:

{
  "path/to/your/service-specifications/MyService.edmx": {
    "directoryName": "my-service",
    "basePath": "/odata/v2",
    "packageName": "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).
• 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	Default	Description
-i, --input (required)	-	Specify the path to the directory or file containing the OData service definition(s) to generate clients for. Accepts definitions as XML and EDMX files. Throws an error if the path does not exist.
-o, --outputDir (required)	-	Directory to save the generated code in.
--optionsPerService	-	Set the path to a file containing the options per service. The configuration allows to set a directoryName and packageName for every service, identified by the path to the original file. It also makes sure that names do not change between generator runs. If a directory is passed, an options-per-service.json file is read/created in this directory.
--overwrite	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.
--generateTypedocJson	true	Generates a typedoc.json file for each package, used for the corresponding "doc" npm script.
--packageJson	false	Generate a package.json file, specifying dependencies and scripts for compiling and generating documentation.
--include	''	Glob describing additional files to be added to the each generated service directory - relative to input.
-t, --transpile	false	Transpile the generated TypeScript code. When enabled, a default tsconfig.json will be generated and used. It emits .js, .js.map and .d.ts files. To configure transpilation set --tsconfig.
--tsconfig	default tsconfig	Replace the default tsconfig.json by passing a path to a custom configuration. By default, a tsconfig.json is only generated when transpilation is enabled (--transpile). If a directory is passed, a tsconfig.json file is read from this directory.
--transpilationProcesses	16	Number of processes used for transpilation of JavaScript files.
-p, --prettierConfig	default prettier config	Configuration file for prettier if you want to change the default value.
--verbose	false	By default, only errors, warnings and important info logs will be displayed. If set to true, all logs will be displayed.
--skipValidation	false	Generation will stop if objects need renaming due to non-unique conditions or conflicts with certain SDK reserved keywords (e.g. Entity, Service, etc.). If you enable this option, conflicts are resolved by appending postfixes like '_1'"
-c, --config	-	Set the path to the file containing the options for generation. If other flags are used, they overwrite the options set in the configuration file. If a directory is passed, a config.json file is read from this directory.

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 input = 'service-specifications';
const outputDir = 'odata-client';

// Create your project datastructure with all sourcefiles based on your options
const generatorConfig = {
  overwrite: true,
  transpile: false,
  readme: false,
  clearOutputDir: true,
  generateTypedocJson: false,
  packageJson: false
  /* optional:
    optionsPerService: 'test/directory',
    include: 'glob of files to include'
  */
};

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

npm Packages Versus Local Clients

The SAP Cloud SDK OData client generator generates TypeScript code. By default, it creates only the TypeScript sources.

If you want to use the generated client in your TypeScript code without sharing it, you can work with the default configuration. If you work with JavaScript, you can enable and configure transpilation with the --transpile and --tsconfig flags.

If you want to publish a generated client to an npm registry, in addition to transpiling, you will need a package.json file for the client. You can generate it with the --packageJson flag or include a custom package.json with the --include flag. Make sure to check intellectual property regulations before publishing to a public registry.

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 --transpile enabled). The generated .js and .map.js files are not meant for humans to read and should be excluded from formatting.