Requirements

• JAVA 11 version is the minimal version supported. It might already be installed on your machine. To install JDK follow (the official instructions)[https://www.oracle.com/java/technologies/downloads/].
• Node.js 22 LT later versions.

Development

Warning: Do not make any manual changes in the generated folder

Code Generation

Step 1: Add Your OpenAPI Specification

Download your OpenAPI specification file (in either JSON or YAML format) and place it in the root directory of your project.

Step 2: Create a Configuration File

In your project's root directory, create a file named oroapi.config.cjs. This file tells the code generator where to find your specification and where to place the output files.

module.exports = {
    // Path to your OpenAPI specification file.
    input: 'specification.yml',
    // Directory where the generated code will be saved.
    output: 'generated'
};

Step 3: Run the Generator

Execute the following command in your terminal to generate the code.

pnpm run generate-sdk

Testing

The project includes comprehensive Jest tests for the OpenAPI-generated SDK.

Setup Testing environment

1. Download the specification file for the storefront, which contains all entities, and place it in the root of this package. Also, the specification file may be generated via the command line: php bin/console oro:api:doc:open-api:dump --view=frontend_rest_json_api --format=yaml > specification.yml
2. Java is installed on a local machine to generate the SDK.
3. Run pnpm run generate-sdk and then pnpm run build to prepare for writing unit tests.

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage report
pnpm test:coverage

Test Coverage

Tests cover:

• API endpoint calls (GET, OPTIONS)
• Request parameter handling (filters, pagination, sorting, includes)
• Custom headers (X-Localization-ID, X-Currency)
• Error handling (4xx, 5xx responses)
• Network error handling
• Configuration options

See tests/README.md for more details.

Fixing code generation

The generator may not correctly handle certain types, such as Mixed, because of circular dependencies in their type declarations. It may be necessary to manually edit the specification file to resolve these dependencies.

An example of how to fix the mixed property is shown in the code snippet below.

    mixed:
        type: object
        anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
            - type: object
              additionalProperties:
                  $ref: '#/components/schemas/mixed'
            - type: array
              items:
                  $ref: '#/components/schemas/mixed'